
















VMS Debugger Manual 

Order Number: AA-LA59D-TE 

November 1991 

This manual explains the features of the VMS Debugger for 
programmers in high-level languages and assembly language. 


Revision/Update Information: 
Software Version: 


This manual supersedes the VMS 
Debugger Manual, Version 5.4. 

VMS Version 5.5 


Digital Equipment Corporation 
Maynard, Massachusetts 






November 1991 

The information in this document is subject to change without notice and should not be construed 
as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no 
responsibility for any errors that may appear in this document. 

The software described in this document is furnished under a license and may be used or copied 
only in accordance with the terms of such license. 

No responsibility is assumed for the use or reliability of software on equipment that is not supplied 
by Digital Equipment Corporation or its affiliated companies. 

Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions 
as set forth in subparagraph (c)(l)(ii) of the Rights in Technical Data and Computer Software 
clause at DEARS 252.227-7013. 

© Digital Equipment Corporation 1991. 

All Rights Reserved. 

The postpaid Reader’s Comments forms at the end of this document request your critical evaluation 
to assist in preparing future documentation. 

The following are trademarks of Digital Equipment Corporation: DECwindows, Digital, VAX, VMS, 
and the DIGITAL logo. 

ZK4538 


This document was prepared using VAX DOCUMENT, Version 2.0. 




Contents 


Preface. xix 


Part I Using the Debugger: DECwindows Interface 


1 Introduction to the Debugger: DECwindows Interface 

1.1 Overview of the Debugger. 

1.2 Starting a Debugging Session. 1-2 

1.2.1 Compiling and Linking a Program to Prepare for Debugging. 1-3 

1.2.2 Establishing the Debugging Configuration. 1-3 

1.2.3 Invoking the Debugger. 

1.3 Debugger Windows and Menus. 1 

1.3.1 Debugger Main Window. 1“6 

1.3.2 Debugger Predefined Windows. 1 — 9 

1.3.2.1 Predefined Source Window (SRC). 1-10 

1.3.2.2 Predefined Output Window (OUT). 1-10 

1.3.2.3 Predefined Automatic Window (AUTO). 1-11 

1.3.2.4 Predefined Instruction Window (INST). 1-11 

1.3.2.5 Predefined Register Window (REG). 1-12 

1.3.3 Using the Pop-Up Menu. 1-12 

1.4 Getting Started with the Debugger. 1-12 

1.4.1 Setting a Breakpoint. 

1.4.2 Executing the Program to the Breakpoint. 1-13 

1.4.3 Executing the Program into a Called Routine. 1-14 

1.4.4 Displaying the Current Value of a Variable. 1—15 

1.4.5 Assigning a Value to the Variable. 1—16 

1.4.6 Displaying Source Code for the Calling Routine . 1—17 

1.5 Using the Debugger. 1“18 

1.5.1 Displaying Online Help About the Debugger. 1-18 

1 . 5 . 1.1 Displaying Context-Sensitive Help . 1-19 

1.5.1.2 Displaying the Overview Help Topic and Subtopics. 1-19 

1.5.1.3 Displaying Help About the Debugger’s Command Interface. 1-19 

1.5.2 Debugger Diagnostic Messages . 1 —20 

1.5.3 Interrupting Program Execution and Aborting Debugger 

Operations. 1~20 

1.5.4 Ending a Debugging Session. 1-20 

1.5.5 Displaying Source Code. 1-21 

1.5.6 Displaying Decoded VAX Instructions. 1-21 

1.5.7 Specifying Address Expressions in Dialog Boxes. 1-22 









































1.5.8 Controlling and Monitoring Program Execution. 1-22 

1.5.8.1 Starting or Resuming Program Execution. 1-23 

1.5.8.2 Executing the Program by Step Unit. 1-23 

1.5.8.3 Suspending and Tracing Execution with Breakpoints and 

Tracepoints . 1-23 

1.5.8.4 Monitoring Changes in Variables with Watchpoints. 1-24 

1.5.9 Examining and Manipulating Program Data. 1-24 

1.5.9.1 Operations with Variables. 1-24 

1.5.9.2 Operations with Code Locations. 1-24 

1.5.9.3 Operations with Addresses or Registers. 1-25 

1.5.9.4 Evaluating Language Expressions. 1-25 

1.5.10 Controlling Access to Symbols in Your Program. 1—25 

1.5.10.1 Setting and Canceling Modules. 1-26 

1.5.10.2 Resolving Symbol Ambiguities. 1-26 

1.5.11 Using the Debugger’s Command Interface. 1-27 

1.5.12 Using Log Files, Initialization Files, and Command Procedures. 1-27 

1.5.13 Debugging Multilanguage Programs. 1-28 

1.5.14 Debugging Shareable Images. 1-28 

1.5.15 Debugging Tasking (Multithread) Programs . 1-28 

1.5.16 Debugging Multiprocess Programs. 1-29 

1.5.17 Debugging Vectorized Programs. 1 -29 

1.5.18 Using the Keypad to Enter Commands. 1-29 

1.6 Additional Options for Invoking the Debugger. 1-31 

1.6.1 Invoking the Debugger from a FileView Window. 1-31 

1.6.2 Invoking the Debugger with the DCL DEBUG Command. 1-31 

1.6.3 Overriding the Debugger’s Default Interface. 1-32 

1.6.3.1 Displaying the Debugger’s DECwindows Interface on Another 

Workstation. 1-32 

1.6.3.2 Displaying the Debugger’s Command Interface in a DECterm 

Window. 1_33 

1.6.3.3 Displaying the Command Interface and Program Input/Output in 

Separate DECterm Windows. 1-33 

1.6.3.4 Explanation of DBG$DECW$DISPLAY and DECW$DISPLAY .. . 1-34 

1.7 Sample Program EIGHTQUEENS. 1-35 


Part II Using the Debugger: Command Interface 
2 Introduction to the Debugger: Command Interface 


2.1 Overview of the Debugger. 2-1 

2.1.1 Functional Features. 2-2 

2.1.2 Convenience Features. 2-3 

2.2 Getting Started with the Debugger. 2-4 

2.2.1 Compiling and Linking a Program to Prepare for Debugging. 2-5 

2.2.2 Establishing the Debugging Configuration. 2-6 

2.2.3 Invoking the Debugger. 2-6 

2.2.4 Ending a Debugging Session. 2-6 

2.2.5 Interrupting Program Execution and Aborting Debugger 

Commands. 2-7 

2.2.6 Entering Debugger Commands . 2-7 

2.2.7 Displaying Source Code. 2-8 

2.2.7.1 Noscreen Mode.. 2-8 

2.2.7.2 Screen Mode. 2-10 














































2.2.8 Controlling and Monitoring Program Execution. 2-12 

2.2.8.1 Starting or Resuming Program Execution. 2-12 

2.2.8.2 Executing the Program by Step Unit. 2-13 

2.2.8.3 Determining Where Execution Is Suspended. 2—13 

2.2.8.4 Suspending Program Execution with Breakpoints. 2-14 

2.2.8.5 Tracing Program Execution with Tracepoints . 2-15 

2.2.8.6 Monitoring Changes in Variables with Watchpoints. 2-15 

2.2.9 Examining and Manipulating Program Data. 2-17 

2.2.9.1 Displaying the Value of a Variable. 2—17 

2.2.9.2 Assigning a Value to a Variable. 2-18 

2.2.9.3 Evaluating Language Expressions. 2-19 

2.2.10 Controlling Access to Symbols in Your Program. 2-19 

2.2.10.1 Setting and Canceling Modules. 2-20 

2.2.10.2 Resolving Symbol Ambiguities. 2-20 

2.3 A Sample Debugging Session. 2-21 

2.4 Debugger Command Summary . 2-25 

2.4.1 Starting and Ending a Debugging Session. 2-25 

2.4.2 Controlling and Monitoring Program Execution. 2-25 

2.4.3 Examining and Manipulating Data. 2-26 

2.4.4 Controlling Type Selection and Radix. 2-26 

2.4.5 Controlling Symbol Lookup and Symbolization. 2-26 

2.4.6 Displaying Source Code. 2-27 

2.4.7 Using Screen Mode. 2-27 

2.4.8 Editing Source Code. 2-28 

2.4.9 Defining Symbols. 2-28 

2.4.10 Using Keypad Mode. 2-28 

2.4.11 U sing Command Procedures. Log Files, and Initialization Files. 2-28 

2.4.12 Using Control Structures. 2-29 

2.4.13 Debugging Multiprocess Programs. 2-29 

2.4.14 Additional Commands. 2-29 


3 Controlling and Monitoring Program Execution 

3.1 Starting and Ending a Debugging Session. 3-1 

3.1.1 Invoking the Debugger with the DCL RUN Command. 3-1 

3.1.2 Invoking the Debugger with the DCL DEBUG Command. 3—3 

3.1.3 Ending a Debugging Session. 3-4 

3.2 Interrupting and Resuming a Debugging Session. 3-4 

3.3 Commands Used to Execute the Program. 3—5 

3.4 Executing the Program by Step Unit. 3-6 

3.4.1 Changing the STEP Command Behavior. 3-7 

3.4.2 Stepping Into and Over Routines. 3-7 

3.5 Suspen ding and Tracing Execution with Breakpoints and Tracepoints . . . 3-8 

3.5.1 Setting Breakpoints or Tracepoints on Individual Program 

Locations. 3-10 

3.5.1.1 Specifying Symbolic Addresses. 3—10 

3.5.1.2 Specifying Locations in Memory. 3-11 

3.5.1.3 Obtaining and Symbolizing Memory Addresses. 3-12 

3.5.2 Setting Breakpoints or Tracepoints on Lines or Instructions. 3-12 

3.5.3 Controlling Debugger Action at Breakpoints or Tracepoints . 3-13 

3.5.4 Setting Breakpoints or Tracepoints on Exceptions. 3—14 

3.5.5 Setting Breakpoints or Tracepoints on Events. 3-14 

3.5.6 Canceling Breakpoints or Tracepoints. 3-15 

3.6 Monitoring Changes in Variables and Other Program Locations. 3-15 
























































3.6.1 Watchpoint Options. 3-17 

3.6.2 Watching Nonstatic Variables . 3-17 

3.6.2.1 Execution Speed. 3-18 

3.6.2.2 Setting a Watchpoint on a Nonstatic Variable. 3-19 

3.6.2.3 Options for Watching Nonstatic Variables. 3-19 

3.6.2.4 Setting Watchpoints in Installed Writable Shareable Images .... 3-20 

3.7 How the Debugger Controls Program Execution. 3-20 

4 Examining and Manipulating Program Data 

4.1 General Concepts. 4-1 

4.1.1 Accessing Variables While Debugging. 4—1 

4.1.2 Using the EXAMINE Command . 4-2 

4.1.3 Using the DEPOSIT Command. 4-3 

4.1.4 Address Expressions and Their Associated Types. 4—4 

4.1.5 Evaluating Language Expressions. 4—5 

4.1.5.1 Using Variables in Language Expressions. 4-6 

4.1.5.2 Numeric Type Conversion by the Debugger. 4-7 

4.1.6 Address Expressions Compared to Language Expressions. 4—7 

4.1.7 Specifying the Current, Previous, and Next Entity. 4—8 

4.1.8 Language Dependencies and the Current Language. 4—10 

4.1.9 Specifying a Radix for Entering or Displaying Integer Data. 4—10 

4.1.10 Obtaining and Symbolizing Memory Addresses. 4-12 

4.2 Examining and Depositing into Variables. 4—14 

4.2.1 Scalar Types. 4—14 

4.2.2 ASCII String Types. 4—15 

4.2.3 Array Types. 4—16 

4.2.4 Record Types. 4-17 

4.2.5 Pointer (Access) Types. 4-18 

4.3 Examining and Depositing VAX Instructions. 4—18 

4.3.1 Examining VAX Instructions. 4-19 

4.3.2 Depositing VAX Instructions. 4-21 

4.4 Examining and Depositing into Registers. 4-22 

4.4.1 The Processor Status Longword (PSL). 4—22 

4.5 Specifying a Type When Examining and Depositing. 4-23 

4.5.1 Defining a Type for Locations Without a Symbolic Name. 4-23 

4.5.2 Overriding the Current Type. 4—24 

4.5.2.1 Integer Types. 4-25 

4.5.2.2 ASCII String Type. 4-26 

4.5.2.3 User-Declared Types. 4-26 

5 Controlling Access to Symbols in Your Program 

5.1 Controlling Symbol Information When Compiling and Linkin g. 5-2 

5.1.1 Compiling. 5-3 

5.1.2 Local and Global Symbols. 5-4 

5.1.3 Linking . 5-4 

5.1.4 Controlling Symbol Information in Debugged Images. 5-5 

5.2 Setting and Canceling Modules. 5-6 

5.3 Resolving Symbol Ambiguities. 5-7 

5.3.1 Symbol Lookup Conventions. 5-8 
















































5.3.2 Using SHOW SYMBOL and Path Names to Specify Symbols 

Uniquely. 5-9 

5.3.2.1 Simplifying Path Names. 5-9 

5.3.2.2 Specifying Symbols in Routines on the Call Stack. 5—10 

5.3.2.3 Specifying Global Symbols. 5-10 

5.3.2.4 Specifying Routine Invocations . 5—10 

5.3.3 Using SET SCOPE to Specify a Symbol Search Scope. 5-11 

5.4 Debugging Shareable Images. 5-12 

5.4.1 Compiling and Linking Shareable Images for Debugging. 5-12 

5.4.2 Accessing Symbols in Shareable Images. 5—13 

5.4.2.1 Accessing Symbols in the PC Scope (Dynamic Mode). 5-14 

5.4.2.2 Accessing Symbols in Arbitrary Images. 5-14 

5.4.2.3 Accessing Universal Symbols in Run-Time Libraries and System 

Images. 5-15 


6 Controlling the Display of Source Code 

6.1 How the Debugger Obtains Source Code Information. 6-1 

6.2 Specifying the Location of Source Files. 6—2 

6.3 Displaying Source Code by Specifying Line Numbers. 6-3 

6.4 Displaying Source Code by Specifying Code Address Expressions. 6-4 

6.5 Displaying Source Code by Searching for Strings . 6-6 

6.6 Controlling Source Display After Stepping and at Event Points. 6-7 

6.7 Setting Margins for Source Display. 


7 Using Screen Mode 

7.1 Concepts and Terminology. 7-2 

7.2 Debugger Predefined Displays . . . .. 7-4 

7.2.1 Predefined Source Display (SRC). 7-4 

7.2.1.1 Displaying Source Code in Arbitrary Program Locations. 7-6 

7.2.1.2 Displaying Source Code for a Routine on the Call Stack. 7-6 

7.2.2 Predefined Output Display (OUT). 7-6 

7.2.3 Predefined Prompt Display (PROMPT). 7-7 

7.2.4 Predefined Instruction Display (INST). 7-7 

7.2.4.1 Displaying the Instruction Display . 7-8 

7.2.4.2 Displaying Instructions in Arbitrary Program Locations. 7-9 

7.2.4.3 Displaying Instructions for a Routine on the Call Stack. 7-9 

7.2.5 Predefined Register Display (REG). 7-9 

7.3 Manipulating Existing Displays. 7-10 

7.3.1 Scrolling a Display. 7-11 

7.3.2 Showing, Hiding, Removing, and Canceling a Display. 7-11 

7.3.3 Moving a Display Across the Screen. 7-12 

7.3.4 Expanding or Contracting a Display. 7-12 

7.4 Creating a New Display.. 7-12 

7.5 Specifying a Display Window. 7—13 

7.5.1 Specifying a Window in Terms of Lines and Columns. 7—13 

7.5.2 Predefined Windows. 7-14 

7.5.3 Creating a New Window Definition. 7-14 

7.6 Specifying the Display Kind. 7-14 

7.6.1 DO (Commandt; . . . ]) Display Kind. 7-15 

7.6.2 INSTRUCTION Display Kind. 7-16 

7.6.3 INSTRUCTION (Command) Display Kind. 7-16 

7.6.4 OUTPUT Display Kind. 7-16 


vii 

























































7.6.5 REGISTER Display Kind. 7-17 

7.6.6 SOURCE Display Kind. 7-17 

7.6.7 SOURCE (Command) Display Kind. 7-18 

7.6.8 PROGRAM Display Kind. 7-18 

7.7 Assigning Display Attributes. 7-18 

7.8 A Sample Display Configuration. 7-20 

7.9 Saving Displays and the Screen State. 7-21 

7.10 Changing the Screen Height and Width. 7-22 

8 Additional Convenience Features 

8.1 Using Debugger Command Procedures. 8-1 

8.1.1 Basic Conventions. 8-1 

8.1.2 Passing Parameters to Command Procedures. 8-2 

8.2 Using a Debugger Initialization File. 8-4 

8.3 Logging a Debugging Session into a File. 8-5 

8.4 Defining Symbols for Commands, Address Expressions, and Values. 8-6 

8.4.1 Defining Symbols for Commands. 8-6 

8.4.2 Defining Symbols for Address Expressions. 8-7 

8.4.3 Defining Symbols for Values . 8-7 

8.5 Assigning Commands to Function Keys. 8-7 

8.5.1 Basic Conventions. 8-8 

8.5.2 Advanced Techniques. 8-8 

8.6 Using Control Structures to Enter Commands. 8-9 

8.6.1 FOR Command. 8-9 

8.6.2 IF Command. 8-9 

8.6.3 REPEAT Command. 8-10 

8.6.4 WHILE Command. 8-10 

8.6.5 EXITLOOP Command. 8-10 

8.7 Calling Routines Independently of Program Execution. 8—10 

9 Debugging Special Cases 

9.1 Debugging Optimized Code. 9-1 

9.1.1 Eliminated Variables. 9_2 

9.1.2 Changes in Coding Order. 9-3 

9.1.3 Use of Registers. 9—4 

9.1.4 Use of Condition Codes. 9-4 

9.2 Debugging Screen-Oriented Programs. 9—5 

9.2.1 Setting the Protection to Allocate a Terminal . 9-6 

9.3 Debugging Multilanguage Programs. 9-6 

9.3.1 Controlling the Current Debugger Language. 9-7 

9.3.2 Specific Differences Among Languages . 9-8 

9.3.2.1 Default Radix. 9_8 

9.3.2.2 Evaluating Language Expressions. 9-8 

9.3.2.3 Arrays and Records. 9-8 

9.3.2.4 Case Sensitivity. 9_9 

9.3.2.5 Initialization Code. 9-9 

9.3.2.6 Ada Predefined Breakpoints. 9—9 

9.4 Debugging Exceptions and Condition Handlers. 9-10 

9.4.1 Setting Breakpoints or Tracepoints on Exceptions. 9-10 

9.4.2 Resuming Execution at an Exception Breakpoint. 9-11 


viii 

















































9.4.3 Effect of Debugger on Condition Handling. 

9.4.3.1 Primary Handler. 

9.4.3.2 Secondary Handler. 

9.4.3.3 Call-Frame Handlers (Application-Declared). 

9.4.3.4 Final and Last-Chance Handlers. 

9.4.4 Exception-Related Built-In Symbols. 

9.5 Debugging Exit Handlers. 

9.6 Debugging AST-Driven Programs. 

9.6.1 Disabling and Enabling the Delivery of ASTs . 

9.6.2 Call Frames Associated with ASTs in SHOW CALLS Display 


9-13 

9-13 

9-13 

9-13 

9-14 

9-15 

9-15 

9-16 

9-16 

9-16 


Debugging Multiprocess Programs 

10.1 Getting Started. 

10.1.1 Establishing a Multiprocess Debugging Configuration. 

10.1.2 Invoking the Debugger. 

10.1.3 Visible Process and Process-Specific Commands . 

10.1.4 Obtaining Information About Processes. 

10.1.5 Bring ing a Spawned Process Under Debugger Control. 

10.1.6 Broadcasting Commands to Specified Processes. 

10.1.7 Controlling Execution .. 

10.1.7.1 Controlling Execution with SET MODE NOINTERRUPT . . 

10.1.7.2 Putting Specified Processes on Hold.. 

10.1.8 Changing the Visible Process. 

10.1.9 Dynamic Process Setting. 

10.1.10 Monitoring the Termination of Images. 

10.1.11 Ending the Debugging Session. 

10.1.12 Terminating Specified Processes . 

10.1.13 Interrupting Program Execution. 

10.2 Supplemental Information. 

10.2.1 Debugging Configurations and Process Relationships. 

10.2.1.1 Establishing a Default Debugging Configuration. 

10.2.1.2 Establishing a Multiprocess Debugging Configuration. 

10.2.1.3 Process Relationships When Debugging. 

10.2.2 Specifying Processes in Debugger Commands. 

10.2.3 Monitoring Process Activation and Termination . 

10.2.4 Interrupting the Execution of an Image to Connect It to the 

Debugger . 

10.2.4.1 Using the Ctrl/Y-DEBUG Sequence to Invoke the Debugger 

10.2.4.2 Using the CONNECT Command to Interrupt an Image . . . 

10.2.5 Screen Mode Features for Multiprocess Debugging. 

10.2.6 Setting Watchpoints in Globed Sections. 

10.2.7 Using Multiprocess Commands with the Default Configuration. 

10.2.8 Advanced Concepts and Possible Errors. 

10.2.9 System Requirements for Multiprocess Debugging. 

10.2.9.1 User Quotas. 

10.2.9.2 System Resources. 


10-1 

10-1 

10-1 

10-2 

10-2 

10-4 

10-5 

10-5 

10-6 

10-6 

10-7 

10-7 

10-8 

10-8 

10-9 

10-9 

10-9 

10-9 

10-10 

10-10 

10-10 

10-11 

10-12 

10-12 

10-12 

10-13 

10-14 

10-15 

10-15 

10-16 

10-16 

10-17 

10-17 



















































11 Debugging Vectorized Programs 

11.1 Obtaining Information About the Vector Processor. 11-2 

11.2 Controlling and Monitoring the Execution of Vector Instructions . 11-2 

11.2.1 Executing the Program to the Next Vector Instruction. 11-3 

11.2.2 Setting Breakpoints and Tracepoints on Vector Instructions. 11-3 

11.2.3 Setting Watchpoints on Vector Registers. 11-3 

11.3 Examining and Depositing into Vector Registers. 11-4 

11.3.1 Specifying the Vector Registers and Vector Control Registers. 11-4 

11.3.2 Examining and Depositing into the Vector Count Register (VCR) .... 11-4 

11.3.3 Examining and Depositing into the Vector Length Register (VLR) ... 11-4 

11.3.4 Examining and Depositing into the Vector Mask Register (VMR) .... 11-5 

11.3.5 Examining and Depositing into the Vector Registers (VO to VI5) .... 11-6 

11.4 Examining and Depositing Vector Instructions. 11-8 

11.4.1 Examining Vector Instructions and Their Operands. 11-9 

11.4.2 Depositing Vector Instructions. 11-12 

11.5 Using a Mask When Examining Vector Registers or Instructions. 11-13 

11.5.1 Using VMR as the Default Mask. 11-13 

11.5.2 Using a Slice of VMR as the Mask. 11-15 

11.5.3 Using a Mask Other Than VMR. 11-15 

11.6 Examining Composite Vector Address Expressions. 11-16 

11.7 Displaying the Results of Vector Floating-Point Exceptions. 11-19 

11.8 Controlling Scalar-Vector Synchronization. 11-19 

11.9 Calling Routines That Might Affect the Program’s Vector State . 11-22 

11.10 Displaying Vector Register Data in Screen Mode. 11-23 

12 Debugging Tasking Programs 

12.1 Comparison of DECthreads and Ada Terminology. 12—2 

12.2 Sample Tasking Programs. 12-2 

12.2.1 Sample C Multithread Program. 12-2 

12.2.2 Sample Ada Tasking Program. 12-6 

12.3 Specifying Tasks in Debugger Commands. 12-10 

12.3.1 Definition of Active Task and Visible Task. 12-10 

12.3.2 Ada Tasking Syntax. 12-11 

12.3.3 Task ID. 12-12 

12.3.4 Task Built-In Symbols. 12-13 

12.3.4.1 Caller Task Symbol (Ada) . 12-14 

12.4 Obtaining Information About Tasks. 12-15 

12.4.1 Obtaining Information about DECthreads Tasks. 12-15 

12.4.2 Obtaining Task Information About Ada Tasks. 12-19 

12.5 Changing Task Characteristics . 12-22 

12.5.1 Putting Tasks on Hold to Control Task Switching. 12-23 

12.5.2 Debugging Programs That Use Time Slicing. 12-23 

12.6 Controlling and Monitoring Execution. 12-24 

12.6.1 Setting Task-Specific and Task-Independent Debugger 

Eventpoints. 12-24 

12.6.2 Setting Breakpoints on DECthreads Tasking Constructs. 12-25 

12.6.3 Setting Breakpoints on Ada Task Bodies, Entry Calls, and Accept 

Statements. 1 2-25 

12.6.4 Monitoring Task Events. 12-27 

12.7 Additional Task-Debugging Topics. 12-30 

12.7.1 Debugging Programs with Deadlock Conditions. 12-30 

12.7.2 Automatic Stack Checking in the Debugger. 12-31 

12.7.3 Using Ctrl/Y When Debugging Ada Tasks. 12-32 


x 
















































c\j eo 


Debugger Command Dictionary 

1 Debugger Command Format. 

1.1 General Format. CD-3 

1.2 Entering Commands at the Keyboard. CD-4 

1.3 Entering Commands in Command Procedures. CD-4 

Debugger Diagnostic Messages . CD-5 

Commands Recognized Only on Workstations Running VWS . CD-5 

Debugger Command Dictionary. CD-6 

@ (Execute Procedure). CD-7 

ATTACH . CD-9 

CALL. CD-10 

CANCEL ALL. CD-15 

CANCEL BREAK. CD-I 7 

CANCEL DISPLAY. CD-20 

CANCEL IMAGE. CD-22 

CANCEL MODE. CD-23 

CANCEL MODULE. CD-24 

CANCEL RADIX. CD-26 

CANCEL SCOPE. CD-27 

CANCEL SOURCE. CD-28 

CANCEL TRACE. CD-30 

CANCEL TYPE/OVERRIDE. CD-33 

CANCEL WATCH. CD-34 

CANCEL WINDOW. CD-35 

CONNECT. CD-36 

Ctrl/C. CD-38 

Ctrl/W, Ctrl/Z. CD-40 

Ctrl/Y. CD-41 

DECLARE. CD-44 

DEFINE. CD-47 

DEFINE/KEY. CD-49 

DEFINE/PROCESS_GROUP. CD-52 

DELETE. CD-54 

DELETE/KEY. CD-56 

DEPOSIT. CD-58 

DISABLE AST. CD-64 

DISPLAY. CD-65 

DO. CD-72 

EDIT. CD-74 

ENABLE AST. CD-76 

EVALUATE. CD-77 

EVALUATE/ADDRESS . CD-79 

EXAMINE. CD-81 

EXIT. CD-90 

EXITLOOP. CD-93 

EXPAND. CD-94 

EXTRACT. CD-97 


XI 
























































FOR. CD-99 

GO. CD-100 

HELP. CD-102 

IF. CD-103 

MOVE. CD-I 04 

QUIT. CD-106 

REPEAT. CD-109 

SAVE. CD-110 

SCROLL. CD-112 

SEARCH. CD-114 

SELECT. CD-117 

SET ABORT.KEY. CD-121 

SETATSIGN. CD-123 

SET BREAK. CD-124 

SET DEFINE. CD-133 

SET EDITOR. CD-134 

SET EVENT_FACILITY. CD-I 36 

SET IMAGE. CD-138 

SET KEY. CD-140 

SET LANGUAGE. CD-I 41 

SET LOG. CD-143 

SET MARGINS. CD-144 

SET MAX_SOURCE_FILES . CD-147 

SET MODE. CD-148 

SET MODULE. CD-I 52 

SET OUTPUT. CD-155 

SET PROCESS . CD-157 

SET PROMPT. CD-161 

SET RADIX. CD-164 

SET SCOPE. CD-I 66 

SET SEARCH. CD-170 

SET SOURCE. CD-172 

SET STEP. CD-175 

SET TASK. CD-178 

SET TERMINAL. CD-181 

SET TRACE. CD-I 83 

SET TYPE. CD-191 

SET VECTOR_MODE. CD-194 

SET WATCH. CD-196 

SET WINDOW. CD-202 

SHOW ABORT.KEY. CD-204 

SHOW AST. CD-205 

SHOW ATSIGN. CD-206 

SHOW BREAK. CD-207 

SHOW CALLS. CD-209 

SHOW DEFINE. CD-211 

SHOW DISPLAY. CD-212 























































SHOW EDITOR. 

SHOW EVENTJFACILITY. 

SHOW EXIT.HANDLERS. 

SHOW IMAGE. 

SHOW KEY.. 

SHOW LANGUAGE. 

SHOW LOG. 

SHOW MARGINS. 

SHOW MAX_SOURCE_FILES . . . 

SHOW MODE. 

SHOW MODULE. 

SHOW OUTPUT. 

SHOW PROCESS . 

SHOW RADIX. 

SHOW SCOPE. 

SHOW SEARCH. 

SHOW SELECT. 

SHOW SOURCE. 

SHOW STACK. 

SHOW STEP. 

SHOW SYMBOL. 

SHOW TASK. 

SHOW TERMINAL. 

SHOW TRACE. 

SHOW TYPE. 

SHOW VECTOR_MODE. 

SHOW WATCH. 

SHOW WINDOW. 

SPAWN. 

STEP. 

SYMBOLIZE. 

SYNCHRONIZE VECTOR_MODE 

TYPE. 

WHILE . 


CD-214 

CD-215 

CD-216 

CD-217 

CD-218 

CD-220 

CD-221 

CD-222 

CD-223 

CD-224 

CD-225 

CD-228 

CD-229 

CD-234 

CD-235 

CD-237 

CD-238 

CD-239 

CD-241 

CD-242 

CD-243 

CD-246 

CD-249 

CD-250 

CD-252 

CD-253 

CD-254 

CD-255 

CD-256 

CD-258 

CD-263 

CD-264 

CD-266 

CD-268 


A Command Defaults 

B Predefined Key Functions 

B.1 DEFAULT, GOLD, BLUE Functions. 

B.2 Key Definitions Specific to LK201 Keyboards- 

B.3 Keys That Scroll, Move, Expand, Contract Displays 

B.4 Online Keypad Key Diagrams. 

B.5 Debugger Key Definitions . 


B-1 

B-3 

B-3 

B-4 

B-5 


xiii 












































C Screen Mode Reference Information 

C.1 Display Kinds . C-1 

C.2 Display Attributes. C-2 

C.3 Predefined Displays. C-3 

C.3.1 SRC (Source Display). C-3 

C.3.2 OUT (Output Display). C-4 

C.3.3 PROMPT (Prompt Display). C—4 

C.3.4 INST (Instruction Display). C-5 

C.3.5 REG (Register Display). C-5 

C.4 Screen-Related Built-In Symbols. C-5 

C.4.1 Screen Height and Width . C-6 

C.4.2 Display Built-In Symbols. C-6 

C. 5 Screen Dimensions and Predefined Windows. C-7 

D Built-In Symbols and Logical Names 

D. 1 SS$_DEBUG Condition. D-1 

D.2 Logical Names. D-1 

D.3 Built-In Symbols. D-2 

D.3.1 Specifying the VAX Registers. D-3 

D.3.2 Constructing Identifiers. D-4 

D.3.3 Counting Parameters Passed to Command Procedures. D-4 

D.3.4 Determining the Debugger Interface (Command or DECwindows) . . . D-5 

D.3.5 Controlling the Input Radix. D-5 

D.3.6 Specifying Program Locations and the Current Value of an Entity . . . D-5 

D.3.7 Using Symbols and Operators in Address Expressions. D-6 

D.3.8 Obtaining Information About Exceptions. D-9 

D. 3.9 Specifying the Current, Next, and Previous Scope on the Call 

Stack. D-10 

E Summary of Debugger Support for Languages 

E. 1 Ada . E-2 

E.1.1 Ada Names and Symbols. E-2 

E. 1.1.1 Ada Names . E-2 

E. 1.1.2 Predefined Attributes. E-3 

E.1.1.2.1 Specifying Attributes with Enumeration Types. E-4 

E.1.1.2.2 Resolving Overloaded Enumeration Literals. E-4 

E.1.2 Operators and Expressions . E-5 

E.1.2.1 Operators in Language Expressions. E-5 

E.1.2.2 Language Expressions. E-6 

E.1.3 Data Types. E-6 

E.1.4 Compiling and Linking. E-7 

E.1.5 Source Display. E-7 

E.1.6 EDIT Command. E-8 

E.1.7 GO and STEP Commands. E-9 

E.1.8 Debugging Ada Library Packages . E-9 

E.1.9 Predefined Breakpoints. E-10 

E. 1.10 Monitoring Exceptions. E-10 

E. 1.10.1 Monitoring Any Exception. E-10 

E. 1.10.2 Monitoring Specific Exceptions . E-11 

E.1.10.3 Monitoring Handled Exceptions and Exception Handlers. E-12 


xiv 
















































E.1.11 Examining and Manipulating Data. E—12 

E.1.11.1 Records . E-13 

E. 1.11.2 Access Types . E-13 

E.1.12 Module Names and Path Names. E-14 

E.1.13 Symbol Lookup Conventions. E-15 

E. 1.14 Setting Modules. E-15 

E. 1.14.1 Identifying Related Modules. E—16 

E. 1.14.2 Setting Modules for Package Bodies . E-17 

E.1.15 Resolving Overloaded Names and Symbols. E-17 

E.1.16 CALL Command. E-18 

E.2 BASIC. E-19 

E.2.1 Operators in Language Expressions. E-19 

E.2.2 Constructs in Language and Address Expressions. E—19 

E.2.3 Data Types. E-20 

E.2.4 Compiling for Debugging. E-20 

E.2.5 Constants. E-20 

E.2.6 Evaluating Expressions. E-20 

E.2.7 Line Numbers. E-20 

E.2.8 Stepping into Routines. E-20 

E.2.9 Symbolic References. E - 21 

E.2.10 Watchpoints. E-2'\ 

E.3 BLISS . E “ 21 

E.3.1 Operators in Language Expressions. E-21 

E.3.2 Constructs in Language and Address Expressions. E—22 

E.3.3 Data Types. E-22 

E.4 C. E-23 

E.4.1 Operators in Language Expressions. E-23 

E.4.2 Constructs in Language and Address Expressions. E—24 

E.4.3 Data Types. E-24 

E.4.4 Case Sensitivity. E-24 

E.4.5 Static and Nonstatic Variables. E-25 

E.4.6 Scalar Variables.. E-25 

E.4.7 Arrays. E-25 

E.4.8 Character Strings. E-25 

E.4.9 Structures and Unions. E-26 

E.5 COBOL. E “29 

E.5.1 Operators in Language Expressions. E-29 

E.5.2 Constructs in Language and Address Expressions. E-30 

E.5.3 Data Types. E-30 

E.5.4 Source Display. E- 31 

E.6 DIBOL. E "31 

E.6.1 Operators in Language Expressions. E-31 

E.6.2 Constructs in Language and Address Expressions. E-32 

E.6.3 Data Types. E-32 

E.7 FORTRAN. E ~3 2 

E.7.1 Operators in Language Expressions. E-32 

E.7.2 Constructs in Language and Address Expressions. E-33 

E.7.3 Predefined Symbols. E-34 

E.7.4 Data Types. E-34 

E.7.5 Initialization Code. E-35 

E.8 MACRO-32. E-35 

E.8.1 Operators in Language Expressions. E-35 

E.8.2 Constructs in Language and Address Expressions. E-36 

E.8.3 Data Types. E-36 


xv 































































E.9 Pascal . E-37 

E.9.1 Operators in Language Expressions. E—37 

E.9.2 Constructs in Language and Address Expressions. E-38 

E.9.3 Predefined Symbols. E-38 

E.9.4 Built-In Functions. E-38 

E.9.5 Data Types. E-38 

E.9.6 Additional Information. E-39 

E.9.7 Restrictions. E-39 

E.10 PL/I. E-39 

E.10.1 Operators in Language Expressions. E-40 

E.10.2 Constructs in Language and Address Expressions. E-40 

E.10.3 Data T^pes. E-40 

E.10.4 Static and Nonstatic Variables. E-41 

E.10.5 Examining and Manipulating Data. E-41 

E. 10.5.1 EXAMINE Command Examples. E-41 

E. 10.5.2 Notes on Debugger Support. E-42 

E.11 RPGII. E-43 

E.11.1 Operators in Language Expressions. E-43 

E.11.2 Constructs in Language and Address Expressions. E-43 

E.11.3 Data Types. E-43 

E.11.4 Setting Breakpoints or Tracepoints. E-44 

E.11.4.1 Setting Breakpoints or Tracepoints Within Specifications. E-44 

E.11.4.2 Setting Breakpoints or Tracepoints on Labels. E-45 

E.11.5 EXAMINE Command. E—45 

E.11.6 DEPOSIT Command. E-46 

E.11.7 EDIT Command. E-46 

E.12 SCAN. E-46 

E.12.1 Operators in Language Expressions. E-47 

E.12.2 Constructs in Language and Address Expressions. E-47 

E.12.3 Predefined Symbols. E-47 

E.12.4 Data Types. E-47 

E.12.5 Names. E-48 

E.12.6 Controlling Execution . E-48 

E.12.6.1 Breakpoints and Tracepoints. E-48 

E.12.6.2 Watchpoints. E-49 

E.12.7 Examining and Depositing. E-49 

E.12.7.1 STRING Variables. E^19 

E. 12.7.2 FILL Variables. E-50 

E.12.7.3 POINTER Variables. E-50 

E. 12.7.4 TREE and TREEPTR Variables.. E-50 

E.12.7.5 RECORD and OVERLAY Variables. E-51 

E.13 Language UNKNOWN. E-52 

E.13.1 Operators in Language Expressions. E-52 

E.13.2 Constructs in Language and Address Expressions. E-52 

E.13.3 Predefined Symbols. E-53 

E.13.4 Data Types. E-53 


xvi 


















































Examples 

1—1 CommandProcedureSEPARATE_WINDOW.COM. 1—34 

1- 2 Sample Program EIGHTQUEENS. 1 —36 

2- 1 Sample Program SQUARES. 2-21 

2-2 Sample Debugging Session Using Program SQUARES. 2-22 

12-1 Sample C Multithread Program.. 12-3 

12-2 Sample Ada Tasking Program. 12-7 

12-3 Sample SHOW TASK/ALL Display for DECthreads Tasks . 12-15 

12-4 Sample SHOW TASK/FULL Display for a DECthreads Task . 12-16 

12-5 Sample SHOW TASK/STAT/FULL Display for DECthreads Tasks ... 12-19 

12-6 Sample SHOW TASK/ALL Display for Ada Tasks. 12-19 

12-7 Sample SHOW TASK/FULL Display for an ADA Task. 12-20 

12-8 Sample SHOW TASK/STATISTICS/FULL Display for Ada Tasks- 12-22 

Figures 

1-1 Debugger Windows at Startup. 1”5 

1-2 Debugger Main Window. 1“6 

1-3 Main Window Pull-Down Menus. 1-7 

1-4 Data Menu and Submenus. I -7 

1—5 Customize Menu and Submenus... I - 8 

1-6 Pop-Up Menu over Source Window. 1 - 12 

1-7 Source Window at Debugger Startup. 1-13 

1-8 Setting a Breakpoint with the Pop-Up Menu. 1-14 

1-9 Execution Suspended at Line 60. 1-14 

1-10 Stepping into a Called Routine. 1 - 15 

1—11 Execution Suspended Within the Called Routine. 1—15 

1—12 Examining a Selected Variable with the Pop-Up Menu. 1—16 

1—13 Assigning a Value to a Variable. 1—17 

1—14 Displaying Source Code in the Calling Routine. 1—18 

1— 15 Keypad Key Functions Predefined by the Debugger—DEC windows 

Interface. 1-30 

2— 1 Keypad Key Functions Predefined by the Debugger—Command 

Interface. 2-9 

2-2 Default Screen Mode Display Configuration . 2-11 

7-1 Default Screen Mode Display Configuration . 7-2 

7-2 Screen Mode Source Display When Source Code Is Not Available .... 7-5 

7-3 Screen Mode Instruction Display. 7- 8 

7-4 Screen Mode Register Display. 7-10 

11- 1 Masked Loading of Array Elements from Memory into a Vector 

Register. 11-12 

12- 1 Diagram of a Task Stack. 12-18 

B-1 Keypad Key Functions Predefined by the Debugger—Command 

Interface. ^-2 










































Tables 

1-1 Main Window Pull-Down Menus. 1-8 

1-2 Main Window Status Region. 1-9 

1-3 Main Window Buttons. 1-9 

3-1 Controlling Debugger Activation with the LINK and RUN 

Commands. 3-3 

5-1 Compiler Options for DST Symbol Information. 5-3 

5-2 Effect of Compiler and Linker on DST and GST Symbol 

Information. 5-5 

10-1 Debugging States. 10-3 

10-2 Process Specifications. 10-11 

12-1 Comparison of DECthreads and Ada Terminology. 12-2 

12-2 Task Built-In Symbols. 12-14 

12-3 Generic Task States. 12-16 

12-4 DECthreads Task Substates. 12-16 

12-5 Ada Task Substates. 12-19 

12-6 Generic Low-Level Task Scheduling Events. 12-27 

12-7 DECthreads-Specific Events. 12-28 

12-8 Ada-Specific Events. 12-28 

12-9 Ada Tasking Deadlock Conditions and Debugger Commands for 

Diagnosing Them. 12-31 

CD-I Debugging States. CD-231 

B-1 Key Definitions Specific to LK201 Keyboards . B-3 

B-2 Keys That Change the Key State. B-4 

B—3 Keys That Invoke Online Help to Display Keypad Diagrams. B—5 

B-4 Debugger Key Definitions . B-5 
































Preface 


Intended Audience 

This manual is for programmers at all levels of experience. It covers both user 
interfaces of the debugger: 

• The VMS DECwindows interface, for workstations 

• The command interface, for terminals and workstations 

The debugger can be used with most VAX languages. This manual emphasizes 
usage that is common to all or most languages. For additional information 
that is specific to a particular language, see Appendix E and the documentation 
furnished with that language. 

Note that you can use the VMS Debugger only to debug code in user mode. You 
cannot debug any code in supervisor, executive, or kernel modes. If you need 
to debug code in other than user mode, refer to the VMS Delta /XDelta Utility 
Manual. 

Document Structure 

This manual is organized in two parts: 

• Part I introduces the debugger’s DECwindows interface. Additional 
information about the DECwindows interface is available through online 
help, as explained in Chapter 1. 

• Part II completely describes the debugger’s command interface: 

— Chapter 2 introduces the command interface. 

— The remaining chapters provide task-oriented and conceptual information. 
To simplify the discussions, many details about the debugger commands 
are not included in these chapters. 

— The command dictionary provides complete reference information about 
all debugger commands. 

— The appendixes provide reference details about specific subjects. 

Associated Documents 

General information about the VMS DECwindows interface is available in the 
VMS DECwindows User’s Guide. 

Information about compiling and debugging that is specific to a particular 
language is available in the documentation furnished with that language and in 
Appendix E of this manual. 

Information about VAX assembly-language instructions and the VAX MACRO 
assembler is available in the VAX MACRO and Instruction Set Reference Manual. 
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Information about the linking of programs and about shareable images is 
available in the VMS Linker Utility Manual. 

Conventions 

The following conventions are used in this manual: 

mouse The term mouse refers to any pointing device, such as a 

mouse, puck, or stylus. 

MB1, MB2, MB3 MB1 indicates the left mouse button, MB2 indicates the 


Ctrl/x 

middle mouse button, and MB3 indicates the right mouse 
button. (The buttons can be redefined by the user.) 

A sequence such as Ctrl/x indicates that you must hold down 
the Ctrl key while you press another key or a pointing device 
button. 

PFl x 

A sequence such as PFl x indicates that you must first press 
and release the PFl key and then press and release another 
key or a pointing device button. 

| Return | 

In examples, a key name is enclosed in a box to indicate that 
you press a key on the keyboard. (In text, a key name is not 
enclosed in a box.) 

In examples, a horizontal ellipsis indicates one of the 
following possibilities: 

• Additional optional arguments in a statement have been 
omitted. 

• The preceding item or items can be repeated one or more 
times. 

• Additional parameters, values, or other information can 
be entered. 

o 

A vertical ellipsis indicates an omission in a code example 
because the omitted items are not important to the topic 
being discussed. 

In format descriptions, parentheses indicate that, if you 
choose more than one option, you must enclose the choices in 
parentheses. 

□ 

In format descriptions, brackets indicate that whatever is 
enclosed within the brackets is optional; you can select none, 
one, or all of the choices. (Brackets are not, however, optional 
in the syntax of a directory name in a file specification or 
in the syntax of a substring specification in an assignment 
statement.) 

u 

In format descriptions, braces surround a required choice of 
options; you must choose one of the options listed. 

red ink 

Red ink indicates information that you must enter from the 
keyboard or a screen object that you must choose or click on. 

For online versions of the book, user input is shown in bold. 

numbers 

Unless otherwise noted, all numbers in the text are assumed 
to be decimal. Nondecimal radixes—binary, octal, or 
hexadecimal—are explicitly indicated. 
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_ Parti 

Using the Debugger: DECwindows Interface 


This part introduces the VMS debugger’s DECwindows interface. Additional 
information about the DECwindows interface is available through online help. 

For information about the debugger’s command interface, see Part II. 
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Introduction to the Debugger: DECwindows 

Interface 


This chapter introduces the VMS debugger’s DECwindows interface and provides 
enough information to get you started. For information about the debugger’s 
command interface, see Part II of this manual, which starts with Chapter 2. 

The following information is provided in this chapter: 

• An overview of the debugger’s main features 

• Instructions to prepare your program for debugging and start a debugging 
session 

• An overview of the debugger windows and menus 

• A sample session to get you started with the debugger 

• Introductions to most of the functions you can perform with the debugger. 

Many topics are covered very briefly. The documentation for the debugger’s 
DECwindows interface consists mainly of online help, and this chapter includes 
numerous references to specific topics in the debugger’s Help menu, in the main 
window. The debugger’s online help system is explained in Section 1.5.1. 

To use this chapter most effectively, read it while running the debugger on your 
workstation. 

It is assumed that you are familiar with the general DECwindows environment 
as described in the VMS DECwindows User's Guide —that is, you should know 
how to use the pointer and keyboard to manipulate windows, menus, dialog 
boxes, online help, and so on. 

If you are already familiar with the debugger’s command interface, including how 
to invoke the debugger from DCL level (as described in Part II of this manual), 
you can start with Section 1.2.3. 

1.1 Overview of the Debugger 

The debugger is a tool that helps you locate run-time programming or logic 
errors, also known as bugs. You use the debugger with a program that has 
been compiled and linked successfully but does not run correctly. For example, 
the program might give incorrect output, go into an infinite loop, or terminate 
prematurely. 

You locate errors with the debugger by observing and manipulating your program 
interactively as it executes. The debugger enables you to do the following tasks: 

• Control the program’s execution—start the program, stop at points of interest, 
resume execution, and so on 

• Trace the execution path of the program 
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• Monitor changes in variables and other program entities 

• Monitor exception conditions and language-specific events 

• Examine and modify the values of variables, or force events to occur 

• In some cases, test the effect of modifications without having to edit the 
source code, recompile, and relink 

These are the basic debugging techniques. After you are satisfied that you have 
found the error in the program, you can edit the source code and compile, link, 
and execute the corrected version. 

As you use the debugger and its documentation (particularly the online help), you 
will discover variations on the basic techniques. You can also tailor the debugger 
for your own needs. 

The debugger is a symbolic debugger. You can specify variable names, routine 
names, and so on, precisely as they appear in your source code. You do not 
need to specify memory addresses or VAX registers when referring to program 
locations, although you can, if you want. 

You can use the debugger with the following VAX languages: 

Ada 

BASIC 

BLISS 

C 

COBOL 

DIBOL 

FORTRAN 

MACRO-32 

Pascal 

PL/I 

RPGII 

SCAN 

The debugger recognizes the syntax, data typing, operators, expressions, scoping 
rules, and other constructs of a given language. If your program is written 
in more than one language, you can change the debugging context from one 
language to another during a debugging session. 

1.2 Starting a Debugging Session 

The usual way to invoke the debugger from a DECterm window is as follows: 

1. Compile and link the program with the /DEBUG command qualifier. 

2. Make sure that the debugging configuration (default or multiprocess) is 
appropriate for the kind of program you are going to debug. 

3. Invoke the debugger by entering the DCL command RUN. 

These steps are explained in the following sections. Additional options for 
invoking the debugger are discussed in Section 1.6. 
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1.2.1 Compiling and Linking a Program to Prepare for Debugging 

Before you can use the debugger, you must compile and link the modules 
(compilation units) of your program as explained in this section. The following 
example shows how to compile and link a Pascal program, consisting of a single 
compilation unit named EIGHTQUEENS, before using the debugger. 

_ Note - 

The /DEBUG and /NOOPTIMIZE qualifiers are compiler command 
defaults for some languages. These qualifiers are used in the example for 
emphasis. 


$ PASCAL/DEBUG/NOOPTIMIZE EIGHTQUEENS 
$ LINK/DEBUG EIGHTQUEENS 

The /DEBUG qualifier on the compiler command (PASCAL in this case) directs 
the compiler to write the symbol information associated with EIGHTQUEENS 
into the object module, EIGHTQUEENS.OBJ, in addition to the code and data for 
the program. This symbol information enables you to use the names of variables 
and other symbols declared in EIGHTQUEENS in debugger dialog boxes and 
commands. If your program has several compilation units, you must compile each 
unit whose symbols you want to reference with the /DEBUG qualifier. 

Some compilers optimize the object code to reduce the size of the program or 
to make it run faster. In such cases you should compile your program with the 
/NOOPTIMIZE command qualifier (or equivalent) when preparing for debugging. 
Otherwise, the contents of some program locations might be inconsistent with 
what you would expect from viewing the source code. (After the program has 
been debugged, you will probably want to recompile it without the /NOOPTIMIZE 
qualifier to take advantage of optimization.) 

The /DEBUG qualifier on the LINK command directs the linker to include all 
symbol information that is contained in EIGHTQUEENS.OBJ in the executable 
image. The qualifier also causes the VMS image activator to start the debugger 
at run time. If your program has several object modules, you need to specify 
those modules in the LINK command, for most languages. 

1.2.2 Establishing the Debugging Configuration 

Before invoking the debugger as explained in Section 1.2.3, check that the 
debugging configuration is appropriate for the kind of program you are going to 
debug. 

You can invoke the debugger in either the default configuration or the 
multiprocess configuration to debug programs that run in either one or several 
processes, respectively. The configuration depends on the current definition of 
the logical name DBG$PROCESS. Thus, before invoking the debugger, enter the 
DCL command SHOW LOGICAL DBG$PROCESS to determine the definition of 
DBG$PROCESS. 

Most of this chapter covers programs that run in only one process. For such 
programs, DBG$PROCESS either should be undefined, as in the following 
example, or should have the value DEFAULT: 

$ SHOW LOGICAL DBG$PROCESS 

%SHOW-S-NOTRAN, no translation for logical name DBG$PROCESS 
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If DBG$PROCESS has the value MULTIPROCESS, and you want to debug a 
program that runs in only one process, enter the following command: 

$ DEFINE DBG$PROCESS DEFAULT 

For more information about multiprocess debugging, see Section 1.5.16. 

1.2.3 Invoking the Debugger 

After you compile and link your program and establish the appropriate debugging 
configuration, you can then invoke the debugger. To do so, enter the DCL 
command RUN, specifying the executable image of your program as the 
parameter. For example, enter the following command to debug the program 
EIGHTQUEENS: 

$ RUN EIGHTQUEENS 

By default, the debugger comes up in the following three windows, arranged as 
shown in Figure 1-1: 

• The main window. 

• The predefined source window SRC, which shows the source code of the 
module you are debugging. The numbers shown at the left of the source code 
are compiler-generated line numbers, as they might appear in a compiler¬ 
generated listing file. 

• The predefined output window OUT, which displays the debugger’s output. 
For example, it shows the value of a variable that you are exa mi ning. 
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Figure 1-1 Debugger Windows at Startup 
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Windows SRC and OUT are two examples of the kinds of debugger windows you 
can use to capture and display different types of data. 

The message that is displayed in window OUT at debugger startup indicates 
that this debugging session is initialized for a Pascal program and that the name 
of the main program unit (the module containing the image transfer address) 
is EIGHTQUEENS. The initialization sets up language-dependent debugger 
parameters. 

By default, the boxed line in window SRC indicates where execution is currently 
suspended. When you start a debugging session, the debugger usually suspends 
execution at the beginning of the main program (line 1, in this example). For Ada 
programs and certain other kinds of programs, execution is initially suspended 
at the beginning of initialization code, before the main program, so that you can 
choose to execute that code under debugger control. To execute to the beginning 
of the main program in such cases, click on the Go button in the main window. 
See your language documentation for more information. 

You can now use the debugger to start execution, set breakpoints, examine 
variables, and so on, as explained in Section 1.4 and Section 1.5. Section 1.3 gives 
an overview of the debugger's windows and menus. 
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1.3 Debugger Windows and Menus 

The debugger windows consist of a main window and several predefined windows 
that capture and display different kinds of data. The following sections briefly 
describe these windows and the pop-up menu, which is available from any 
debugger window. 

For more information, choose Overview from the Help menu, then choose 
Debugger Windows and Menus. 

1.3.1 Debugger Main Window 

The debugger’s main window (see Figure 1-2) includes a menu bar, a status 
region, and four buttons that are labeled Go, Step, Examine, and Stop. 

Figure 1-2 Debugger Main Window 
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• Figure 1-3 shows the menus on the main window’s menu bar. Figure 1-4 
and Figure 1-5 show the submenus of the Data and Customize menus, 
respectively. Table 1-1 summarizes the functions of these menus and 
submenus. 

• Table 1-2 summarizes the type of information displayed in the status region 
fields and the functions of the associated arrow buttons. 

• Table 1-3 summarizes the functions of the Go, Step, Examine, and Stop 
buttons. 

Note that the functions of the Go, Step, and Examine buttons can also be 
performed through other means, such as the pop-up menu, Control menu, or 
Data menu. 
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Figure 1-3 Main Window Pull-Down Menus 
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Figure 1-4 Data Menu and Submenus 
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Figure 1-5 Customize Menu and Submenus 
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Table 1-1 Main Window Pull-Down Menus 


Menu 

Description 

File 

End the debugging session. 

Edit 

Copy text to the clipboard, or paste text from the clipboard to a debugger 
dialog box or the COMMAND box. 

Control 

Start, stop, and monitor the execution of your program under debugger 
control. For example: execute to the next line or to the next VAX 
assembly-language instruction; set breakpoints, tracepoints, and 
watchpoints; call a routine. For vectorized programs, force synchronization 
between the scalar and vector processors. 

Data 

Display or manipulate data that is associated with your program. For 
example: examine variables and arbitrary program locations; assign 
new values to variables; evaluate language expressions; control access 
to variable names, routine names, and other symbols; manipulate 
multiprocess programs and tasking (multithread) programs. Note that 
the Tasks menu item is dimmed unless you are debugging a VAX Ada 
program or a program written in any language that uses DECthreads 
tasking services. 

Customize 

Tailor your debugging environment and establish default conditions. 

For example: create and manipulate debugger windows; change the 
programming language context; establish defaults for manipulating 
data and for accessing symbols; open the COMMAND box to access the 
debugger’s command interface. 

Help 

Obtain conceptual and task-oriented information about the debugger. This 
is an alternative to obtaining context-sensitive help on individual items 
that are displayed on the screen (menus, buttons, dialog boxes, and so on). 
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Table 1-2 Main Window Status Region 


Label 

Description 

Current Entity 

Identifies the last entity that was examined or whose value was 
changed (for example, a variable or a code location). Use the 
arrow buttons to display consecutive logical entities—for example, 
consecutive elements of an array variable. 

Call Frame 

Identifies the routine that the debugger uses as reference when 
displaying source code in the source window or instructions in 
the instruction window, or when searching for symbols that are 
associated with your program (variable names, routine names, and 
so on). Use the arrow buttons to reset the reference to another call 
frame on the call stack. 

Visible Process 

For a one-process program, identifies the process that is running 
the program. For a multiprocess program, identifies the process 
that is currently the context for entering process-specific commands. 
Use the arrow buttons to reset the visible process to another process 
that is under debugger control. 


Table 1-3 

Main Window Buttons 

Button 

Description 

Go 

Start execution from the current program location. 

Step 

Execute the program one step unit of execution. By default, this is one 
executable line of source code. 

Examine 

Display the value of a variable or other entity whose name is selected in a 
window, or the value of the entity last examined, if no text was selected. 

Stop 

Interrupt program execution or a debugger operation without ending the 
debugging session. 


1.3.2 Debugger Predefined Windows 

The debugger provides the following predefined windows that you can use to 
capture and display different kinds of data: 

SRC, the predefined source window 
OUT, the predefined output window 

AUTO, the predefined automatic window (a special output window) 

INST, the predefined instruction window 
REG, the predefined register window 

Of these windows, only SRC and OUT are displayed, by default, at debugger 
startup. 

The basic features of the predefined windows are described in the next sections. 
You can change certain characteristics of these windows, such as buffer size 
or window attributes. You can also create additional windows similar to the 
predefined windows. For more information, choose Overview from the Help menu, 
then choose Debugger Windows and Menus, then choose Debugger Predefined 
Windows (SRC, OUT, INST, REG, AUTO). 
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1.3.2.1 Predefined Source Window (SRC) 

You can use window SRC to display source code in two basic ways: 

• By default, SRC automatically displays the source code for the module 
in which execution is currently suspended. This enables you to quickly 
determine your current debugging context. 

• In addition, you can use SRC to display the source code for any part of your 
program. 

The name of the module whose source code is displayed is shown at the right 
of the window name, SRC. The numbers displayed at the left of the source code 
are the compiler-generated line numbers, as they might appear in a compiler¬ 
generated listing file. 

The next paragraphs describe the behavior of SRC when it is displaying the 
current location. Section 1.5.5 explains how to display source code in arbitrary 
locations. 

As you execute the program under debugger control, window SRC is updated 
automatically whenever execution is suspended. The boxed line indicates the 
next line to be executed. 

If the debugger cannot locate source lines for the routine in which execution is 
suspended (because, for example, the routine is a run-time library routine), it 
tries to display source lines in the next routine down on the call stack for which 
source lines are available. If the debugger can display source lines for such a 
routine, it issues the following message: 

%DEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC. 

Displaying source in a caller of the current routine. 

In such cases, the boxed line in the source window identifies the line to which 
execution returns after the routine call. Depending on the source language and 
coding style, this might be the line that contains the call statement or the next 
line. 

If your program was optimized during compilation, the source code displayed in 
window SRC might not always represent the code that is actually executing. The 
predefined instruction window INST is useful in such cases, because it shows the 
exact VAX instructions that are executing. See Section 1.3.2.4. 

1.3.2.2 Predefined Output Window (OUT) 

Window OUT is a general purpose output window. By default, it displays the 
following information: 

• Any debugger output that is not directed to windows SRC, INST, or AUTO. 
For example, if window INST is not displayed or does not have the instruction 
attribute, any output that would otherwise update window INST is displayed 
in window OUT. 

• Debugger diagnostic messages. Messages with a severity level greater than I 
(informational) are also displayed in a message box (see Section 1.5.2). 

Note that, when displaying variable names, routine names, and other symbolic 
address expressions, the debugger adds a path name prefix to the name. The 
path name prefix identifies the nesting program elements in which the entity was 
declared in the program. For example, if you examined a variable K, whose value 
was 26, in routine SWAP of module SWAP_PACK, the debugger might display the 
following output: 
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SWAP_PACK\SWAP\K: 26 

In this case, SWAP_PACK\ SWAP\ is the path name prefix. 

In most cases, you do not need to include a path name prefix when specifying 
symbolic address expressions (see Section 1.5.10.2). 

1.3.2.3 Predefined Automatic Window (AUTO) 

Window AUTO is an automatically updating window that can be used instead 
of window OUT to display the output from the following dialog boxes, which are 
accessible from the Data menu: 

Examine Variable 
Examine Address or Register 
Language Expressions 

Window AUTO is created when you first click on the Display button in any one of 
these dialog boxes. Thereafter, AUTO remains open until you close it. 

AUTO includes a debugger command list in its definition. Every time the 
debugger gains control, AUTO is updated with the output of that command 
list. 

When AUTO is created, its command list consists of the Examine or Evaluate 
command that was generated when you clicked on the Display button, and it 
displays the output of that command. 

Subsequently, every time you click on the Display button in any of the three 
dialog boxes listed, the debugger appends the new command generated to the 
current command list and updates AUTO to display the output from the entire 
command list. 

1.3.2.4 Predefined Instruction Window (INST) 

Window INST displays the decoded VAX assembly-language instruction stream 
of your program. This is the exact code that is executing, including the effects of 
any compiler optimization. 

You can use INST in two basic ways: 

• By default, INST automatically displays the instructions for the routine 
in which execution is currently suspended. This enables you to quickly 
determine your current debugging context. 

• In addition, you can use INST to display the instructions for any part of your 
program. 

By default, INST is not displayed on the screen. To open INST, choose Window 
Setups from the Customize menu. Clicking on a window layout of the Window 
Setups submenu enables you to place INST next to either window SRC or window 
REG. 

If your program was optimized during compilation, the window layout that places 
windows SRC and INST side by side enables you to readily compare the source 
code and the decoded instruction stream. 

See Section 1.5.6 for more information about displaying instructions. 
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1.3.2.5 Predefined Register Window (REG) 

Window REG displays the current values, in hexadecimal format, of the VAX 
general registers (RO to Rll, AP, FP, SP, and PC), the four condition code bits (C, 
V, Z, and N) of the processor status longword (PSL), and as many of the top stack 
values as can be displayed through the window. 

The values contained in the registers are updated each time the debugger gains 
control. 

By default, REG is not displayed on the screen. To open REG, choose Window 
Setups from the Customize menu. Clicking on the third layout of the Window 
Setups submenu enables you to place REG next to window INST. 

1.3.3 Using the Pop-Up Menu 

The debugger’s pop-up menu (see Figure 1-6) enables you to perform several 
common operations without having to pull down a menu in the main window. 

Figure 1-6 Pop-Up Menu over Source Window 



Set Break 

View Current Location 
Go 


For an explanation of the pop-up menu items, use the pop-up menu’s context- 
sensitive help (see Section 1.5.1). All pop-up menu functions can also be 
performed through other means. 

To use the pop-up menu, proceed as follows: 

1. Position the pointer within a debugger window. 

2. Press and hold MB2 to display the pop-up menu, then drag to the desired 
menu item and release MB2. 

Note that the behavior of the Examine, Evaluate, and Set Break menu items 
depends on whether you selected text before invoking the pop-up menu. 

1.4 Getting Started with the Debugger 

This section walks you through the following basic steps with a sample program, 
EIGHTQUEENS. The complete source code for the program is shown in 
Section 1.7. 

1. Set a breakpoint to suspend execution at a routine call statement. 

2. Execute the program to the breakpoint. 

3. Execute the program into the called routine. 


1-12 



























Introduction to the Debugger: DECwindows Interface 
1.4 Getting Started with the Debugger 


4. While execution is suspended within the routine, display the current value of 
a variable. 

5. Assign another value to the variable. 

6. Display source code in the calling routine. 

Figure 1-7 shows the source window, SRC, at debugger startup. Execution is 
suspended at line 1 (the boxed line) of module EIGHTQUEENS. 

Figure 1-7 Source Window at Debugger Startup 



1.4.1 Setting a Breakpoint 

In this section, a breakpoint is set on line 60 of module EIGHTQUEENS. Line 60, 
which is hidden below the window border in Figure 1-7, contains a call to routine 
TRYCOL (see Figure 1-8). 

Proceed as follows: 

1. Scroll the source window to display line 60. 

2. Double click on any part of line 60. When setting a breakpoint, you can select 
any portion of a line in the source window. For example, you could select the 
number 60, as shown in Figure 1-8, or the word TRYCOL. The breakpoint 
would be set on line 60 in either case. 

3. Choose Set Break from the pop-up menu. 

A breakpoint is now set on line 60—specifically, at the beginning of line 60, before 
the call to routine TRYCOL is executed. 

1.4.2 Executing the Program to the Breakpoint 

To execute the program from the current location (line 1) to the breakpoint at line 
60, click on the Go button in the main window. 

When execution reaches the breakpoint, the source window is updated 
automatically: line 60 is boxed, indicating that execution is now suspended 
at the call statement to routine TRYCOL (see Figure 1-9). 
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Figure 1-8 Setting a Breakpoint with the Pop-Up Menu 



Go 


Figure 1-9 Execution Suspended at Line 60 



Whenever the source window is updated as a result of program execution, the 
boxed line indicates the line to be executed next. 

1.4.3 Executing the Program into a Called Routine 

While execution is suspended at line 60, at the call statement to routine TRYCOL, 
choose Step Into Routine from the pop-up menu to execute the program one step 
unit into the routine (see Figure 1-10). 

After this Step command has been entered, the source window is updated, 
showing that execution is now suspended at line 36, within routine TRYCOL (see 
Figure 1-11). 

The Step command is used in this section and the next to execute the program 
one source line at a time. Note that, in this mode of operation, the Step command 
executes one or more executable lines at a time, skipping over any other lines. 
Executable lines are those for which instructions were generated by the compiler. 
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Figure 1-10 Stepping into a Called Routine 



Go 


Figure 1-11 Execution Suspended Within the Called Routine 



1.4.4 Displaying the Current Value of a Variable 

The value of the Boolean variable SAFE is obtained in this section. It is obtained 
after the assignment statement at line 39, in routine TRYCOL, has been executed 
(see Figure 1-11). 

To execute the program from the current location at line 36 past line 39 (for 
example, to line 42), click on the Step button repeatedly until line 42 is boxed (see 
Figure 1-12). 

To display the current value of the variable SAFE, proceed as follows: 

1. Double click on the word SAFE in the source window to select that word. 

2. Choose Examine from the pop-up menu. 

The value of SAFE (True) is now displayed in window OUT. The debugger 
displays the variable name using its full path name (EIGHTQUEENSX SAFE), 
indicating that SAFE is declared in module EIGHTQUEENS. 

Note that the Current Entity field in the main window is now updated to identify 
the last entity that was examined, namely the variable SAFE. 
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Figure 1-12 Examining a Selected Variable with the Pop-Up Menu 
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1.4.5 Assigning a Value to the Variable 

Assume that the variable SAFE is still selected in the source window. To change 
the value of SAFE from True to False, proceed as follows (see Figure 1-13): 

1. Choose Variables from the Data menu in the main window, then choose 
Deposit into Variable... from the submenu. 

When the Deposit into Variable dialog box is displayed, note that the selected 
word, SAFE, fills the Variable text-entry field. Thus, you do not have to enter 
the variable name from the keyboard. 

2. Enter the word False in the Language Expression field. This is the value to 
be assigned to (deposited into) the variable. 

3. Click on OK or Apply. 

Variable SAFE now has the value False. You can verify this by choosing Examine 
from the pop-up menu. 
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Figure 1-13 Assigning a Value to a Variable 
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1.4.6 Displaying Source Code for the Calling Routine 

By default, the source window shows the source code for the routine in which 
execution is suspended, and the name of the routine is identified in the Call 
Frame field of the main window. 

In this example, execution is currently suspended within routine TRYCOL of 
module EIGHTQUEENS. The Call Frame field in Figure 1-12 displays the 
routine path name, EIGHTQUEENSX TRYCOL. 

The number 0 in the Call Frame field indicates that the routine whose source 
code is displayed is the routine at the top of the call stack (where execution is 
suspended). 

If, as in this example, execution is suspended within a called routine, you can 
display the source code for the calling routine by clicking once on the Call Frame 
down arrow button. 

Clicking once displays the source code for routine EIGHTQUEENS (the main 
program), as shown in Figure 1-14. The boxed line identifies the line where 
execution will continue in that routine (line 61, which follows the call statement). 
The Call Frame field now displays the number 1, followed by the name of that 
routine. The number indicates the level, relative to the top of the call stack (level 
0), of the routine whose source code is displayed. 
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Figure 1-14 Displaying Source Code in the Calling Routine 
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In general, clicking on the Call Frame arrow buttons enables you to display the 
source code for any routine up or down the call stack. 

A Call Frame arrow button that is dimmed indicates that the scope reference is 
at the end of the call stack. 

1.5 Using the Debugger 

The remaining sections of this chapter explain how to use the debugger to 
perform basic functions. After an introduction, most sections point to an online 
help topic for additional information. 

1.5.1 Displaying Online Help About the Debugger 

_Note_ 

When you first invoke the debugger’s online help system, it might take 
up to a minute to display the first help topic. Subsequent help topics are 
displayed within a few seconds after you request them. 


Three kinds of online help about the debugger and debugging are available during 
a debugging session: 

• Context-sensitive help, which is available for any item in a debugger window, 
menu, or dialog box 

• Conceptual and task-oriented help, which consists of an introductory help 
topic named Overview and several subtopics on specific subjects 

• Help about the debugger’s command interface, which is available through the 
COMMAND box 

The technique for displaying each kind of online help is described in the following 
sections. 
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1.5.1.1 Displaying Context-Sensitive Help 

Context-sensitive help about the debugger is available for any item in a debugger 
window, menu, or dialog box. 

To display context-sensitive help: 

1. Point to an item. 

2. Press and hold the Help key. 

3. Click on either MB1, MB2, or MB3. 

4. Release the Help key. 

Context-sensitive help for dialog boxes is structured in the following way: 

• The same help text is displayed for any location of the pointer within a dialog 
box. 

• The introductory help text describes how to use the dialog box for a typical 
operation. 

• In most cases, a separate additional topic is devoted to each item in the dialog 
box (button, menu, and so on). These topics are listed in the order that the 
items they describe appear in the dialog box, from top to bottom. 

• Other topics provide task-oriented and conceptual discussions, where 
applicable. 

When using context-sensitive help, you should also display the Overview help 
topic and look for related information in the list of additional topics. 

1.5.1.2 Displaying the Overview Help Topic and Subtopics 

The Overview help topic and subtopics provide conceptual and task-oriented help 
about the debugger and debugging. These topics supplement the information that 
is available through context-sensitive help. 

To display the Overview topic, use any one of the following techniques: 

• Choose Overview from the Help menu in the main window. 

• Ensure that a debugger window has the input focus, then press and release 
the Help key. 

• Choose Go To Overview from the View menu of a debugger help window. 

Then, to obtain information about a particular subject, choose a topic from the 
list of additional topics. 

1.5.1.3 Displaying Help About the Debugger’s Command Interface 

Help about the debugger’s command interface is available through the 
COMMAND box. 

• To open the COMMAND box, choose Show Command... from the Customize 
menu. 

• To list the help topics, enter the HELP command at the DBG> prompt. 

• For an explanation of the command-interface help system, enter the command 
HELP HELP. 
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1.5.2 Debugger Diagnostic Messages 

Debugger diagnostic messages include numerous informational messages (severity 
level I) that provide feedback during a debugging session. (For an explanation 
of severity levels, choose Overview from the Help menu, then choose Debugger 
Diagnostic Messages .) 

To reduce the time involved in acknowledging informational messages, only those 
debugger messages that have severity levels of W, E, or F are displayed in a 
message box. 

You can get context-sensitive help on any debugger message that is displayed in a 
message box. 

By default, all debugger messages (including those of severity level I) are 
displayed in window OUT. Thus, debugger messages of severity level greater than 
I are displayed both in a message box and in window OUT. 

Messages displayed in a message box show only the message text. Messages 
displayed in window OUT show the message text, identifier, severity, and facility. 

1.5.3 Interrupting Program Execution and Aborting Debugger Operations 

To interrupt program execution during a debugging session, click on the Stop 
button in the main window. This is useful if, for example, the program is in an 
infinite loop. 

To abort a debugger operation that is in progress, click on the Stop button in the 
main window. This is useful if, for example, the debugger is displaying a long 
stream of data. 

Clicking on the Stop button does not end the debugging session. Clicking on 
the Stop button when the program is not running or when the debugger is not 
performing an operation has no effect. 

1.5.4 Ending a Debugging Session 

To end a debugging session, choose either Exit or Quit from the File menu in the 
main window. 

If your program has application-declared exit handlers, Exit executes these 
handlers. Quit gives you the option of executing application-declared exit 
handlers (a dialog box is displayed in such cases). 

Unless you are debugging a multiprocess program, you can also end the 
debugging session by choosing Exit or Quit from any debugger window (not 
just the main window). 

For multiprocess programs, choosing Exit or Quit from a debugger window other 
than the main window has the following effect: 

• If the window is not process specific, terminates the visible process 

• If the window is process specific, terminates the process associated with that 
window 

The following message, displayed in the output window during a debugging 
session, indicates that your program has completed normally: 

%DEBUG-I-EXITSTATUS, is '%SYSTEM-S-NORMAL, normal successful completion' 
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If you want to continue debugging after seeing this message, it is usually best to 
end the session and start a new one. You can restart execution from within the 
debugging session (by choosing Go... from the Control menu and then specifying 
a location in the Go dialog box). However, this technique can produce unexpected 
results if, for example, some variables have different values from when you first 
ran the program. 

1.5.5 Displaying Source Code 

By default, window SRC automatically displays the source code for the module in 
which execution is currently suspended. 

In addition, window SRC has the source attribute by default. Therefore, you can 
also use SRC to display the source code for any part of your program (if source 
code is available for display): 

• You can display the source code for any routine on the call stack by clicking 
on the Call Frame arrow buttons in the main window. 

The number shown in the Call Frame field indicates the relative level of the 
routine on the call stack. Call frame 0 denotes the routine at the top of the 
call stack, where execution is suspended. Call frame 1 denotes the calling 
routine, and so on. 

• You can display arbitrary source lines in any module by choosing View 
Source... from the Commands menu of window SRC. 

• You can display the source line associated with a code location (for example, a 
routine declaration) by choosing Examine Code... from the Code submenu of 
the Data menu. 

After manipulating the contents of window SRC, you can display the location at 
which execution is suspended by choosing View Current Location from the pop-up 
menu. 

If the debugger cannot locate source lines for display, it issues a diagnostic 
message. 

For more information, choose Overview from the Help menu, then choose 
Displaying Source Code. 

1.5.6 Displaying Decoded VAX Instructions 

By default, window INST automatically displays the decoded instruction stream 
for the routine in which execution is currently suspended. 

If window INST has the instruction attribute, it is also updated by any command 
that you enter to display instructions. If no window has the instruction attribute, 
the output of such commands is directed at window OUT. Note that opening 
window INST through the Window Setups submenu of the Customize menu 
automatically assigns the instruction attribute to that window. 

You can display instructions in window INST as follows: 

• You can display the instruction stream for any routine that is on the call 
stack by clicking on the Call Frame arrow buttons in the main window. 

• You can display the instructions that are associated with a code location 
(for example, a routine declaration) by choosing View Instructions from the 
Commands menu of window INST, or by choosing Examine Code... from the 
Code submenu of the Data menu. 


1-21 






Introduction to the Debugger: DECwindows Interface 
1.5 Using the Debugger 


When you choose Examine Code..., you have the option of displaying detailed 
information about the instruction operands. 

After manipulating the contents of window INST, you can display the location at 
which execution is suspended by choosing View Current Location from the pop-up 
menu. 

For more information, choose Overview from the Help menu, then choose 
Displaying Decoded VAX Instructions. 

1.5.7 Specifying Address Expressions in Dialog Boxes 

Several dialog boxes (for example, the Break dialog box) require you to enter an 
address expression. An address expression is an entity that denotes a memory 
address or a register. Do not confuse an address expression with a language 
expression, which denotes a value (see Section 1.5.9.4). 

The debugger is a symbolic debugger. Therefore, although you can specify a 
memory address or register directly in a dialog box, you usually specify symbolic 
address expressions. These include routine names, variable names, program 
labels, and source line numbers. The debugger associates a symbolic address 
expression with a unique memory address, range of addresses, or register. The 
debugger also recognizes the compiler-generated type that is associated with a 
symbolic address expression. 

Address expressions are associated with either code (VAX assembly-language 
instructions) or data. The kind of address expression you need to specify in a 
dialog box depends on the action you are about to perform and is indicated in the 
help text for that dialog box. For example, when setting a breakpoint, you specify 
an address expression that is associated with code; when setting a watchpoint, 
you specify an address expression that is associated with data (a variable name, 
in most cases). 

You can fill the Address Expression field of a dialog box in two ways: 

• By selecting text in a window. If you select the text before you open the dialog 
box, the text is automatically inserted in the Address Expression field. 

• By entering text directly from the keyboard. 

The help text for a dialog box explains the conventions for filling the Address 
Expression field. 

For more information, choose Overview from the Help menu, then choose 
Specifying Address Expressions. 

1.5.8 Controlling and Monitoring Program Execution 

This section explains how to perform the following tasks: 

• Start or resume program execution 

• Execute the program to the next source line, instruction, or other step unit 

• Use breakpoints to suspend execution at points of interest 

• Use tracepoints to trace the execution path of your program through specified 
locations 

• Use watchpoints to monitor changes in the values of variables 
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To determine where execution is suspended at any time during a debugging 
session, use the techniques described in Section 1.5.5 and Section 1.5.6. You can 
also choose Call Stack... from the Data menu to display the sequence of routine 
calls that are currently active on the call stack and to obtain detailed information 
about the call stack. 

1.5.8.1 Starting or Resuming Program Execution 

Use the Go command to start or resume program execution. 

To start execution from the current location, click on the Go button in the main 
window. 

To start execution from another location, choose Go... from the Control menu and 
specify the location in the Go dialog box. 

After it is started with the Go command, program execution continues until one 
of the following events occurs: 

• The program completes execution 

• A breakpoint is reached 

• A watchpoint is activated 

• An exception is signaled 

• You click on the Stop button in the main window 

For more information, choose Overview from the Help menu, then choose Starting 
and Resuming Execution (Go Command). 

1.5.8.2 Executing the Program by Step Unit 

Use the Step command to execute the program one or more step units at a time. 

By default, a step unit is one line of source code; and, by default, the debugger 
notifies you of the completion of a Step command by displaying a "stepped 
to " message and the source line where execution is suspended. 

To execute one step unit, click on the Step button in the main window. 

You can use the pop-up menu for some common step options (for example, step 
into routine, step by instruction). 

To execute these and other step options, or to change the step unit or any Step 
command default, choose Step... from the Control menu. For example, you can 
make the default step unit signify "execute one instruction". 

For more information, choose Overview from the Help menu, then choose 
Executing the Program by Step Unit (Step Command). 

1.5.8.3 Suspending and Tracing Execution with Breakpoints and Tracepoints 

A breakpoint is a location in your program at which execution is to be suspended. 
Typical locations are routine declarations, program labels, and specific lines of 
source code. At a breakpoint, you can step into a routine, check the current value 
of a variable, and so on. 

In addition to specifying unique locations, you can set breakpoints on every source 
line or on certain classes of VAX assembly-language instructions. You can also 
set breakpoints on certain kinds of events, such as exceptions and tasking events. 
And you can set conditional breakpoints that trigger only when a specified 
expression is evaluated to be true. 
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A tracepoint is like a breakpoint, except that execution continues after the 
debugger reports that the tracepoint has been reached. Tracepoints enable you 
to monitor the path of execution of your program through specified locations (for 
example, through routine calls). As with breakpoints, you can trace through 
classes of instructions, monitor events, and set conditional tracepoints. 

In general, to set, identify, or cancel breakpoints or tracepoints, choose Break... 
from the Control menu. 

For more information, choose Overview from the Help menu, then choose Using 
Breakpoints and Tracepoints. 

1.5.8.4 Monitoring Changes in Variables with Watchpoints 

A watchpoint is a memory address, register, or (typically) a variable declared in 
the program whose value is monitored during program execution. If the value 
changes, the debugger suspends execution and reports the old and new values. 

Note that you can set a watchpoint on a nonstatic (stack or register) variable only 
when program execution is currently suspended within the scope of its defining 
routine—that is, when the defining routine is active on the call stack. 

To set, identify, or cancel watchpoints, choose Watch... from the Control menu. 

As with breakpoints and tracepoints, you have several options for setting 
watchpoints. 

For more information, choose Overview from the Help menu, then choose Using 
Watchpoints. 

1.5.9 Examining and Manipulating Program Data 

The debugger enables you to manipulate variables declared in your program, code 
locations (locations containing VAX instructions), memory addresses, registers, 
and language expressions. 

1.5.9.1 Operations with Variables 

To manipulate variables in your program, choose Variables from the Data menu. 
The Variables submenu provides the following operations: 

• To display the value of a variable, choose Examine Variable... 

• To assign a value to a variable, choose Deposit into Variable... 

• To display information about a variable, such as its type, memory address or 
register, and path name, choose Show Variable... 

Note that you can examine a nonstatic (stack or register) variable only when 
program execution is currently suspended within the scope of its defining 
routine—that is, when the defining routine is active on the call stack. 

For more information, choose Overview from the Help menu, then choose 
Examining and Manipulating Program Data , then choose Operations with 
Variables. 

1.5.9.2 Operations with Code Locations 

To manipulate code locations in your program (locations with VAX assembly- 
language instructions) choose Code from the Data menu. The Code submenu 
provides the following operations: 

• To display the following information, choose Examine Code... 

— The source line for a code location (for example, for a routine declaration). 
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— The VAX instructions at a code location (for example, the instruction 
at the current PC value, where execution is suspended). The program 
counter (PC) is a VAX register that contains the address of the instruction 
to be executed next. 

• To deposit a VAX instruction at a memory address or into a register, choose 
Deposit Code... 

• To display the memory address of a routine, line number, or other code 
location, choose Show Address... 

For more information, choose Overview from the Help menu, then choose 
Examining and Manipulating Program Data , then choose Operations with Code 
Locations. 

See also Section 1.3.2.4 and Section 1.5.6 for information about displaying 
instructions associated with your program. 

1.5.9.3 Operations with Addresses or Registers 

To manipulate memory addresses or registers, choose Addresses or Registers 
from the Data menu. The Addresses or Registers submenu provides the following 
operations: 

• To display the value stored at an address or in a register, choose Examine 
Address or Register... 

• To change the value stored at an address or in a register, choose Deposit into 
Address or Register... 

• To display the symbol (if any) that is associated with an address or register, 
choose Symbolize Address or Register... 

For more information, choose Overview from the Help menu, then choose 
Examining and Manipulating Program Data , then choose Operations with 
Addresses or Registers. 

1.5.9.4 Evaluating Language Expressions 

To evaluate a language expression, choose Language Expressions... from the Data 
menu. 

The debugger recognizes the operators and expression syntax of the currently set 
language. For example, if your program has an integer variable named WIDTH, 
you can use the Language Expressions dialog box to evaluate the expression 
WIDTH + 7. The debugger adds 7 to the current value of WIDTH and displays 
the result. 

For more information, choose Overview from the Help menu, then choose 
Specifying and Evaluating Language Expressions. See also Section 1.5.13 for 
information about debugging multilanguage programs. 

1.5.10 Controlling Access to Symbols in Your Program 

To have full access to the symbols that are associated with your program (variable 
names, routine names, source code, line numbers, and so on), you must compile 
and link the program using the /DEBUG qualifier, as explained in Section 1.2.1. 

Under these conditions, the way in which the debugger handles these symbols 
is transparent to you, in most cases. However, the following two areas might 
require action: 

• Setting and canceling modules 
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• Resolving symbol ambiguities 

These two subjects are discussed in the next sections. For more information, 
choose Overview from the Help menu, then choose Controlling Access to Symbols 
in Your Program. 

1.5.10.1 Setting and Canceling Modules 

To facilitate symbol searches, the debugger loads symbol information from the 
executable image into a run-time symbol table (RST), where that information can 
be accessed efficiently. Unless symbol information is in the RST, the debugger 
does not recognize or properly interpret the associated symbols. 

Because the RST takes up memory, the debugger loads it dynamically, 
anticipating what symbols you might want to reference in the course of program 
execution. The loading process is called module setting, because all symbol 
information for a given module is loaded into the RST at one time. 

At debugger startup, only the module containing the image transfer address 
is set. Subsequently, whenever execution of the program is interrupted, the 
debugger sets the module that contains the routine in which execution is 
suspended. This enables you to reference the symbols that should be visible 
at that location. 

If you try to reference a symbol in a module that has not been set, the debugger 
warns you that the symbol is not in the RST. For example: 

IDEBUG-W-NOSYMBOL, symbol 'X' is not in symbol table 

You must then set the module containing that symbol explicitly. To set a module, 
choose Modules... from the Data menu. The Modules dialog box lists the modules 
of your program and identifies which modules are set. 

For more information, choose Overview from the Help menu, then choose 
Controlling Access to Symbols in Your Program , then choose Setting and 
Canceling Modules . 

1.5.10.2 Resolving Symbol Ambiguities 

Symbol ambiguities can occur when a symbol (for example, a variable name X) is 
defined in more than one routine or other program unit. 

In most cases, the debugger resolves symbol ambiguities automatically. First 
it uses the scope and visibility rules of the currently set language. In addition, 
because the debugger permits you to specify symbols in arbitrary modules (to set 
breakpoints and so on), the debugger uses the ordering of routine calls on the call 
stack to resolve symbol ambiguities. 

In some cases, however, the debugger might respond as follows when you specify 
a symbol that is defined multiple times: 

• It might issue a "symbol not unique" message because it is not able to 
determine the particular declaration of the symbol that you intended. 

• It might reference a symbol declaration other than the one you want. 

To resolve such problems, you must specify a scope where the debugger should 
search for the particular declaration of the symbol. There are two techniques: 

• Specify a path name prefix with the symbol. For example, if the variable 
X is defined in two modules named COUNTER and SWAP, the path name 
SWAP\X uniquely specifies the declaration of X in module SWAP. This 
technique can always be used to resolve symbol ambiguities. 
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• If the different declarations of the symbol are within routines that are 
currently active on the call stack, use the Call Frame arrow buttons in the 
main window to reset the reference for looking up symbols to the appropriate 
call frame. With this technique you do not need to specify a path name prefix. 

For more information, choose Overview from the Help menu, then choose 
Controlling Access to Symbols in Your Program, then choose Resolving Symbol 
Ambiguities. 

1.5.11 Using the Debugger’s Command Interface 

The debugger is available in a command interface that runs on terminals and 
workstations (see Part II of this manual). When using that interface, you interact 
with the debugger by entering commands at the debugger prompt (DBG>). 

When using the debugger’s DECwindows interface, you can open the COMMAND 
box, which enables you to enter debugger commands at the DBG> prompt: 

• To open the COMMAND box for just one command, press the DO key. 

• To open the COMMAND box indefinitely, choose Show Command... from 
the Customize menu. Choosing Hide Command from that menu closes the 
COMMAND box. 

You can also enter debugger commands in debugger command procedures 
and initialization files for execution under the DECwindows environment (see 
Section 1.5.12). 

The following commands are disabled in the debugger’s DECwindows interface: 

CANCEL WINDOW 

EXPAND 

MOVE 

SELECT/PROGRAM 

SET MARGINS 

SET MODE NOSCREEN 

SET OUTPUT [NO]SCREEN_LOG 

SET OUTPUT [NONTERMINAL 

SET TERMINAL 

SET WINDOW 

SHOW MARGINS 

SHOW TERMINAL 

SHOW WINDOW 

The debugger issues an error message when you try to enter any of these 
commands interactively from the COMMAND box or when the debugger executes 
a command procedure containing any of these commands. 

For more information, choose Overview from the Help menu, then choose Using 
the Debugger’s Command Interface. 

1.5.12 Using Log Files, Initialization Files, and Command Procedures 

When you use the debugger’s DECwindows interface, each of your actions 
results in one or more debugger commands. These commands are echoed in the 
COMMAND box by default. 

You can record in a log file the debugger commands that you enter directly or 
indirectly during a debugging session and the debugger’s responses to those 
commands. You can use log files to keep a record of your debugging sessions, 
or you can use them as command procedures in subsequent sessions. For more 
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information, choose Overview from the Help menu, then choose Logging a 
Debugging Session into a File . 

You can create an initialization file containing debugger commands to set your 
default debugging modes, debugger window characteristics, and so on. When you 
invoke the debugger, those commands are executed automatically to tailor your 
debugging environment. For more information, choose Overview from the Help 
menu, then choose Using a Debugger Initialization File . 

You can direct the debugger to execute a command procedure (a file containing 
a sequence of debugger commands) to re-create a debugging session, to continue 
a previous session, or to avoid typing the same debugger commands many times 
during a debugging session. You can pass parameters to command procedures. 
For more information, choose Overview from the Help menu, then choose Using 
Debugger Command Procedures . 

1.5.13 Debugging Multilanguage Programs 

Within the same debugging session, you can debug modules whose source code is 
written in different languages. 

By default, the debugger language remains set to the language of the main 
program throughout the debugging session, even if execution is suspended 
within a module written in another language. To take full advantage of symbolic 
debugging with such modules, you can set the debugging context to another 
language by choosing Language from the Customize menu. 

For more information, choose Overview from the Help menu, then choose 
Debugging Multilanguage Programs and Debugger Support for Languages. 

When debugging in any language, be sure also to consult the documentation 
supplied with that language. 

1.5.14 Debugging Shareable Images 

By default, the main (executable) image of your program is your debugging 
context. 

By setting your debugging context to a shareable image that is linked with your 
program, you have access to the symbols declared in that image. To set your 
debugging context to another image, choose Images... from the Data menu. 

For more information, choose Overview from the Help menu, then choose 
Debugging Shareable Images . 

1.5.15 Debugging Tasking (Multithread) Programs 

Tasking programs have multiple threads of execution within a VMS process. 
Examples of such programs are programs that use DECthreads or POSIX 1003.4a 
services, and programs that use language-specific tasking services (for example, 
Ada tasking programs). 

When using the debugger with a tasking program, you can control the execution 
of individual tasks and display information about one or more tasks or the entire 
tasking system. 

To manipulate tasks, choose Tasks... from the Data menu. See also Chapter 12 of 
this manual. 
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1.5.16 Debugging Multiprocess Programs 

To debug a multiprocess program (a program that runs in more than one process), 
you must establish a multiprocess debugging configuration before invoking the 
debugger. That configuration enables you to interact with several processes from 
one debugging session. 

Enter the following command to establish a multiprocess debugging configuration: 

$ DEFINE/JOB DBG$PROCESS MULTIPROCESS 

After you have invoked the debugger, you can control the execution of individual 
processes, examine data associated with specific processes, display information in 
process-specific windows, and so on. 

To manipulate processes, choose Processes... from the Data menu. For more 
information, choose Overview from the Help menu, then choose Debugging 
Multiprocess Programs . 

1.5.17 Debugging Vectorized Programs 

When using the debugger with a vectorized program (a program that uses VAX 
vector instructions), you can perform tasks such as the following: 

• Control and monitor the execution of vector instructions with breakpoints, 
watchpoints, and so on 

• Examine and deposit into the vector control registers (VCR, VLR, and VMR) 
and the vector registers (VO to V15) 

• Examine and deposit vector instructions and their operands 

• Perform masked operations on vector registers to display only certain register 
elements or override the masking associated with a vector instruction 

• Control synchronization between the scalar and vector processors 

For more information, choose Overview from the Help menu, then choose 
Debugging Vectorized Programs . 

1.5.18 Using the Keypad to Enter Commands 

When you invoke the debugger, a few commonly used debugger command 
sequences are automatically assigned to the keys on the numeric keypad (to the 
right of the main keyboard). Thus, you can perform certain functions either by 
choosing an item from a menu or by pressing a keypad key. 

The predefined key functions are identified in Figure 1-15. 
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Figure 1-15 Keypad Key Functions Predefined by the Debugger—DECwindows 
Interface 
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Most keypad keys have three predefined functions—DEFAULT, GOLD, and 
BLUE. 

• lb enter a key’s DEFAULT function, press the key. 

• To enter its GOLD function, first press and release the PF1 (GOLD) key, and 
then press the key. 

• To obtain its BLUE function, first press and release the PF4 (BLUE) key, and 
then press the key. 

In Figure 1-15, the DEFAULT, GOLD, and BLUE functions are listed within each 

key’s outline, from top to bottom, respectively. For example: 

• Pressing keypad key 0 enters the STEP command (like clicking on the Step 
button in the main window). 

• Pressing key PF1 and then keypad key 0 enters the STEP/INTO command 
(like choosing Step Into Routine from the pop-up menu). 

• Pressing key PF4 and then keypad key 0 enters the STEP/OVER command 
(like choosing Step Over routine from the pop-up menu). 

You can redefine keypad key functions. 
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For more information, choose Overview from the Help menu, then choose 
Entering Debugger Commands from the Keypad. 

1.6 Additional Options for Invoking the Debugger 

Section 1.2 describes how to compile and link your program prior to debugging, 
establish the default debugging configuration for one-process programs, and 
invoke the debugger in the usual way from a DECterm window. 

The sections that follow describe other options for invoking the debugger: 

• Invoke the debugger from a FileView window 

• Interrupt a program that is executing freely and then invoke the debugger 

• Override the debugger’s default (DECwindows) interface to achieve the 
following: 

— Display the debugger’s DECwindows interface on another workstation 

— Display the debugger’s command interface in a DECterm window, along 
with any program input/output 

— Display the debugger’s command interface and program input/output in 
separate DECterm windows 

In all cases, before invoking the debugger, first compile and link the modules of 
your program and establish the appropriate debugging configuration as explained 
in Section 1.2.1, Section 1.2.2, and Section 1.5.16. 

_ Note - 

You cannot run a program under debugger control over a DECnet link. 

Both the image to be debugged and the debugger must reside on the same 
node. 


For more information, including details on compilation and linking options that 
affect debugging, choose Overview from the Help menu, then choose Options for 
Invoking the Debugger. 

1.6.1 Invoking the Debugger from a FileView Window 

lb invoke the debugger from a FileView window, proceed as follows: 

1. Choose Run from the FileView Files menu. A dialog box is displayed. 

2. Specify the executable image file to be debugged. 

3. Choose the Debug option. 

4. Click on OK. 

1.6.2 Invoking the Debugger with the DCL DEBUG Command 

You can invoke the debugger while your program is executing freely (for example, 
if you suspect that the program might be in an infinite loop or if you see erroneous 
output). 

To invoke the debugger in this manner, proceed as follows: 

1. Enter the DCL command RUN/NODEBUG to execute the program without 
debugger control. 
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2. Press Ctrl/Y to interrupt the executing program. Control then passes to the 
DCL command interpreter. 

3. Enter the DCL command DEBUG to activate the debugger. When the 
debugger comes up, it displays the main, source, and output windows, sets 
the language-dependent parameters to the language of the module where 
execution was interrupted, and executes any user-defined initialization file. 

For example: 

$ PASCAL/DEBUG/NOOPTIMIZE EIGHTQUEENS 

$ LINK/DEBUG EIGHTQUEENS 

$ RUN/NODEBUG EIGHTQUEENS 


fcttW] 

Interrupt 
$ DEBUG 

[invokes debugger] 

To help you identify where execution was interrupted, look at the source window 
and choose Call Stack... from the Data menu to identify the sequence of routine 
calls on the call stack. 

1.6.3 Overriding the Debugger’s Default Interface 

By default, if your workstation is running VMS DECwindows, the debugger comes 
up in the DECwindows interface on the workstation specified by the DECwindows 
application-wide logical name DECW$DISPLAY. 

This section explains how to override the debugger’s default DECwindows 
interface to achieve the following: 

• Display the debugger’s DECwindows interface on another workstation 

• Display the debugger’s command interface in a DECterm window, along with 
any program input/output 

• Display the debugger’s command interface and program input/output in 
separate DECterm windows 

The logical name DBG$DECW$DISPLAY enables you to override the default 
interface of the debugger. Note that, in most cases, there is no need to define 
DBG$DECW$DISPLAY, because the default implies the desired action. 

Section 1.6.3.4 provides more information about the logical names 
DBG$DECW$DISPLAY and DECW$DISPLAY. 

1.6.3.1 Displaying the Debugger’s DECwindows Interface on Another Workstation 

If you are debugging a DECwindows application that uses most of the screen, 
you might find it useful to run the program on one workstation and display the 
debugger’s DECwindows interface on another. To do so, proceed as follows: 

1. Enter a logical definition with the following syntax in the DECterm window 
from which you plan to run the program: 

DEFINE/JOB DBG$DECW$DISPLAY workstationjoathname 

where workstation.pathname is the path name for the workstation where the 
debugger’s DECwindows interface is to come up. See the description of the 
SET DISPLAY command in the VMS DCL Dictionary for the syntax of this 
path name. 
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It is recommended that you use a job definition. If you use a process 
definition, it must not have the CONFINE attribute. 

2. Run the program from that DECterm window. The debugger’s DECwindows 
interface comes up on the workstation specified by DBG$DECW$DISPLAY. 
The application’s windowing interface comes up on the workstation display 
where it normally does. 

1.6.3.2 Displaying the Debugger’s Command Interface in a DECterm Window 

To display the debugger’s command interface in a DECterm window, along with 
any program input/output, proceed as follows: 

1. Enter the following definition in the DECterm window from which you plan 
to run the program: 

$ DEFINE/JOB DBG$DECW$DISPLAY " " 

You can specify one or more space characters between the quotation marks. It 
is recommended that you use a job definition for the logical name. If you use 
a process definition, it must not have the CONFINE attribute. 

2. Run the program from that DECterm window. The debugger’s command 
interface comes up in the same window. 

For example: 

$ DEFINE/JOB DBG$DECW$DISPLAY " " 

$ PASCAL/DEBUG/NOOPTIMIZE EIGHTQUEENS 
$ LINK/DEBOG EIGHTQUEENS 
$ RUN EIGHTQUEENS 

VAX DEBUG Version 5.5 

%DEBUG-I-INITIAL, language is PASCAL, module set to EIGHTQUEENS 
DBG> 

You can now enter debugger commands as described in Part II of this manual, 
which starts with Chapter 2. 

1.6.3.3 Displaying the Command Interface and Program Input/Output in Separate DECterm 
Windows 

This section describes how to display the debugger’s command interface in a 
separate DECterm window from the DECterm window from which you invoke the 
debugger. This separate window is useful when using the command interface to 
debug a screen-oriented program: 

• The program’s input/output is displayed in the window from which you invoke 
the debugger. 

• The debugger’s input/output, including any screen-mode display, is displayed 
in the separate window. 

The effect is the same as entering the SET MODE SEPARATE command at the 
DBG> prompt on a workstation running VWS rather than DECwindows. (The 
SET MODE SEPARATE command is not valid when used in a DECterm window.) 

The following example shows how to display the debugger’s command interface in 
a separate debugger window titled “Debugger”. 

1. Create the command procedure SEPARATE_WINDOW.COM shown in 
Example 1—1. 
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2. Execute the command procedure: 

$ @SEPARATE_WINDOW 

IDCL-I-ALLOC, _MYN0DE$TWA8: allocated 

A new DECterm window is created with the attributes specified in 
SEPARATE_WINDOW.COM. 

3. Follow the steps in Section 1.6.3.2 to display the debugger’s command 
interface. The interface is displayed in the new window. 

4. You can now enter debugger commands in the debugger window. Program 
input/output is displayed in the DECterm window from which you invoked 
the debugger. 

5. When you end the debugging session with the EXIT command, control returns 
to the DCL prompt in the program input/output window, but the debugger 
window remains open. 

6. To display the debugger’s command interface in the same window as the 
program’s input/output (as in Section 1.6.3.2), enter the following commands: 

$ DEASSIGN/JOB DBG$INPUT 
$ DEASSIGN/JOB DBG$OUTPUT 

The debugger window remains open until you close it explicitly. 


Example 1-1 Command Procedure SEPARATE_WINDOW.COM 


$ 

$ 

$ 


$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 


! Simulates effect of SET MODE SEPARATE from a DECterm window 

I 

CREATE/TERMINAL/NOPROCESS - 
/WINDOW_ATTRIBUTES=(TITLE="Debugger\ - 
ICON_NAME="Debugger",R0WS=4 0)- 
/DEFINE_LOGICAL=(TABLE=LNM$JOB,DBG$INPUT,DBG$OUTPUT) 

ALLOCATE DBG$OUTPUT 
EXIT 

I 

! The command CREATE/TERMINAL/NOPROCESS creates a DECterm 
! window without a process. 

j 

! The /WINDOW_ATTRIBUTES qualifier specifies the window's 
! title (Debugger), icon name (Debugger), and the number 
! of rows in the window (40). 

i 

! The /DEFINE_LOGICAL qualifier assigns the logical names 
! DBG$INPUT and DBG$OUTPUT to the window, so that it becomes 
! the debugger input and output device. 

i 

! The command ALLOCATE DBG$OUTPUT causes the separate window 
! to remain open when you end the debugging session. 


1.6.3.4 Explanation of DBG$DECW$DISPLAY and DECW$DISPLAY 

By default, if your workstation is running VMS DECwindows, the debugger comes 
up in the DECwindows interface on the workstation specified by the DECwindows 
application-wide logical name DECW$DISPLAY. DECW$DISPLAY is defined in 
the job table by File View or DECterm. It points to the display device for the 
workstation. 

For information about DECW$DISPLAY, see the description of the DCL 
commands SET DISPLAY and SHOW DISPLAY in the VMS DCL Dictionary. 
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The logical name DBG$DECW$DISPLAY is the debugger-specific equivalent of 
DECW$DISPLAY. DBG$DECW$DISPLAY is analogous to the debugger-specific 
logical names DBG$INPUT and DBG$OUTPUT. These enable you to reassign 
SYS$INPUT and SYS$OUTPUT, respectively, to specify the device on which 
debugger input and output are to appear. 

The default user interface of the debugger results when DBG$DECW$DISPLAY 
is undefined or has the same translation as DECW$DISPLAY. By default, 
DBG$DECW$DISPLAY is undefined. 

The algorithm that the debugger follows when using the logical definitions of 
DECW$DISPLAY and DBG$DECW$DISPLAY is as follows: 

1. If the logical name DBG$DECW$DISPLAY is defined, then use it. Otherwise, 
use the logical name DECW$DISPLAY. 

2. Translate the logical name. If its value is not null (if the string contains 
characters other than space characters), the DECwindows interface comes up 
on the specified workstation. If the value is null (if the string consists only of 
space characters), the command interface comes up in the DECterm window. 

1.7 Sample Program EIGHTQUEENS 

Example 1-2 is the Pascal program, EIGHTQUEENS, that is used in Section 1.4. 
Line numbers correspond to the compiler assigned line numbers as displayed in a 
debugger source window. 

The program prints out the possible locations on a chess board at which each of 
eight queens can be positioned safely, without threatening each other. A queen 
can be threatened by another queen on the same row, in the same column, or 
along a diagonal. 

When executed, the program produces several lines of integers. For example: 

1 5 8 6 3 7 2 4 

1 6 8 3 7 4 2 5 

1 7 4 6 8 2 5 3 

1 7 5 8 2 4 6 3 

2 4 6 8 3 1 7 5 

2 5 7 1 3 8 6 4 


3 7 2 8 6 4 1 5 

3 8 4 7 1 6 2 5 

4 1 5 8 2 7 3 6 

4 1 5 8 6 3 7 2 


8 2 5 3 1 7 4 6 

8 3 1 6 2 5 7 4 

8 4 1 3 6 2 7 5 

Each line of output represents a possible safe configuration of the eight queens 

on a standard 8-row by 8-column chess board. For example, the output line 
41582736 indicates that queens can be positioned safely at rows 4, 1, 5, 8, 2, 7, 3, 
and 6 of columns 1 to 8, respectively. 
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Example 1-2 Sample Program EIGHTQUEENS 


1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 


PROGRAM Eightqueens(OUTPUT); 

VAR 

I : INTEGER; 

A : ARRAY[1..8] OF BOOLEAN; 

B : ARRAY[2..16] OF BOOLEAN; 

C : ARRAY[-7..7] OF BOOLEAN; 

X : ARRAY[1..8] OF INTEGER; 

Safe : BOOLEAN; K: INTEGER; 

PROCEDURE Print; 

BEGIN (* Print *) 

FOR K := 1 TO 8 DO 
WRITE(X[K]: 2); 

WRITELN; 

END; (* Print *) 

PROCEDURE Trycol(J : INTEGER); 

VAR 

I : INTEGER; 

PROCEDURE Setqueen; 

BEGIN (* Setqueen *) 

A[I] := FALSE; 

B [I+.J] := FALSE; 

C[I-J] := FALSE; 

END; (* Setqueen *) 

PROCEDURE Removequeen; 

BEGIN (* Removequeen *) 

A[I] := TRUE; 

B[I+J] := TRUE; 

C[I-J] := TRUE; 

END; (* Removequeen *) 

BEGIN (* Trycol *) 

I := 0; 

REPEAT 
I := 1+1; 

Safe := A[I] AND B[I+J] AND C[I-J]; 
IF Safe THEN 
BEGIN 
Setqueen; 

X[J] := I; 

IF J < 8 THEN 
Trycol(J+l) 

ELSE 

Print; 

Removequeen; 

END; 

UNTIL I = 8; 

END; (* Trycol *) 


(continued on next page) 
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Example 1-2 (Cont.) Sample Program EIGHTQUEENS 


52: 



53: 

BEGIN (* 

Eightqueens : 

54: 

FOR I 

:= 1 TO 8 DO 

55: 

A[I] 

:= TRUE; 

56: 

FOR I 

:= 2 TO 16 DO 

57: 

B [I] 

:= TRUE; 

58: 

FOR I 

:= -7 TO 7 DO 

59: 

C[I] 

:= TRUE; 

60: 

Trycol 

(l); 

61: 

WRITELN; 

62: 

END. (* 

Eightqueens * 
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_ Part II 

Using the Debugger: Command Interface 


¥ 


This part contains complete information about the VMS debugger’s command 
interface. 

For information about the debugger’s DECwindows interface, see Part I. 
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Introduction to the Debugger: Command 

Interface 


This chapter introduces the VMS Debugger’s command interface. For information 
about the debugger’s DECwindows interface, see Chapter 1. 

The following information is provided in this chapter: 

• An overview of the debugger’s features (Section 2.1) 

• Enough information to get you started (Section 2.2) 

• A sample debugging session (Section 2.3) 

• A list of the debugger commands, by function (Section 2.4) 

After you have read this chapter, consult the rest of this manual for additional 
details about the command interface. 

2.1 Overview of the Debugger 

The debugger is a tool that helps you locate run-time programming or logic 
errors, also known as bugs. You use the debugger with a program that has 
been compiled and linked successfully but does not run correctly. For example, 
the program might give incorrect output, go into an infinite loop, or terminate 
prematurely. 

You locate errors with the debugger by observing and manipulating your program 
interactively as it executes. By entering debugger commands at the terminal, you 
can do the following tasks: 

• Control the program’s execution—start the program, stop at points of interest, 
resume execution, and so on 

• Trace the execution path of the program 

• Monitor changes in variables and other program entities 

• Monitor exception conditions and language-specific events 

• Examine and modify the values of variables, or force events to occur 

• In some cases, test the effect of modifications without having to edit the 
source code, recompile, and relink 

These are the basic debugging techniques. After you are satisfied that you have 
found the error in the program, you can edit the source code and compile, link, 
and execute the corrected version. 

As you use the debugger and its documentation, you will discover variations on 
the basic techniques. You can also tailor the debugger for your own needs. The 
next section summarizes the debugger features. 
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2.1.1 Functional Features 

Programming Language Support 

You can use the debugger with the following VAX languages: Ada, BASIC, BLISS, 
C, COBOL, DIBOL, FORTRAN, MACRO-32, Pascal, PL/I, RPG II, and SCAN. 
The debugger recognizes the syntax, data typing, operators, expressions, scoping 
rules, and other constructs of a given language. If your program is written 
in more than one language, you can change the debugging context from one 
language to another during a debugging session with the SET LANGUAGE 
command. 

Symbolic Debugging 

The VMS Debugger is a symbolic debugger. You can refer to program locations by 
the symbols you used for them in your program—the names of variables, routines, 
labels, and so on. You do not need to specify memory addresses or VAX registers 
when referring to program locations, although you can, if you want. 

Support for All Data Types 

The debugger understands all compiler generated data types, such as integer, 
floating point, enumeration, record, array, and so on. It displays the values of 
program variables according to their declared type. 

Flexible Data Format 

The debugger permits a variety of data forms and types for entry and display. By 
default, the source language of the program determines the format used for the 
entry and display of data. You can also impose other formats. For example, by 
using a type or radix qualifier with the EXAMINE command, you can display the 
contents of a program location in ASCII, word-integer, or floating-point format. 

Starting or Resuming Program Execution 

You start or resume program execution with the GO or STEP commands. The 
GO command causes the program to execute until a breakpoint is reached, a 
watchpoint is modified, an exception is signaled, or the program terminates. The 
STEP command enables you to execute a specified number of lines or instructions, 
or up to the next instruction of a specified class. 

Breakpoints 

By setting breakpoints with the SET BREAK command, you can suspend program 
execution at specified locations and check the current status of your program. 
Rather than specify a location, you can also suspend execution on certain classes 
of instructions or on every source line. Also you can suspend execution on certain 
kinds of events, such as exceptions and tasking (multithread) events. 

Tracepoints 

By setting tracepoints with the SET TRACE command, you can monitor the 
path of program execution through specified locations. When a tracepoint 
is triggered, the debugger reports that the tracepoint was reached and then 
continues execution. As with the SET BREAK command, you can also trace 
through classes of instructions and monitor events. 

Watchpoints 

By setting a watchpoint with the SET WATCH command, you can cause execution 
to stop whenever a particular variable or other memory location has been 
modified. When a watchpoint is triggered, the debugger suspends execution 
at that point and reports the old and new values of the variable. 
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Manipulation of Variables and Program Locations 

With the EXAMINE command, you can determine the value of a variable or 
program location. The DEPOSIT command enables you to change that value. You 
can then continue execution to see the effect of the change, without having to 
recompile, relink, and rerun the program. 

Evaluation of Expressions 

With the EVALUATE command, you can compute the value of a source-language 
expression or an address expression. You specify expressions and operators in the 
syntax of the language to which the debugger is currently set. 

Control Structures 

You can use logical control structures (FOR, IF, REPEAT, WHILE) in commands 
to control the execution of other commands. 

Shareable Image Debugging 

You can debug shareable images (images that are not directly executable). 

The SET IMAGE command enables you to reference the symbols declared in 
a shareable image. 

Multiprocess Debugging 

You can debug multiprocess programs (programs that run in more than one VMS 
process). The SHOW PROCESS and SET PROCESS commands enable you to 
display process information and control the execution of images in individual 
processes. 

Task Debugging 

You can debug tasking programs (also known as multithread programs). These 
programs use DECthreads or POSIX 1003.4a services, or use language-specific 
tasking services (for example, Ada tasking programs). The SHOW TASK and SET 
TASK commands enable you to display task information and control the execution 
of individual tasks. 

Vector Debugging 

You can debug vectorized programs (programs that use VAX vector instructions). 
You can control and monitor execution at the vector instruction level, examine 
and deposit vector instructions, manipulate the contents of vector registers, use a 
mask to display specific vector elements, and control synchronization between the 
scalar and vector processors. 

Terminal and Workstation Support 

The debugger supports all VT-series terminals and MicroVAX workstations. 

2.1.2 Convenience Features 

Online Help 

Online help is always available during a debugging session. Online help contains 
information about all debugger commands and selected topics. 

Source Code Display 

You can display lines of source code for all supported languages during a 
debugging session. 
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Screen Mode 

In screen mode, you can display and capture various kinds of information 
in scrollable windows that can be moved around the screen and resized. 
Automatically updated source, instruction, and register displays are available. 
You can selectively direct debugger input, output, and diagnostic messages to 
displays. You can also create "DO" displays that capture the output of specific 
command sequences. 

Keypad Mode 

When you invoke the debugger, several commonly used debugger command 
sequences are assigned by default to the keys of the numeric keypad (if you have 
a VT52, VT100, or LK201 keyboard). Thus, you can enter these commands with 
fewer keystrokes than if you were to type them at the keyboard. You can also 
create your own key definitions. 

Source Editing 

As you find errors during a debugging session, you can use the EDIT command 
to invoke any editor available on your system. You specify the editor you wish 
with the SET EDITOR command. If you use the VAX Language-Sensitive Editor, 
the editing cursor is automatically positioned within the source file whose code 
appears in the screen-mode source display. 

Command Procedures 

You can direct the debugger to execute a command procedure (a file of debugger 
commands) to re-create a debugging session, to continue a previous session, or 
to avoid typing the same debugger commands many times during a debugging 
session. You can pass parameters to command procedures. 

Initialization Files 

You can create an initialization file containing commands to set your default 
debugging modes, screen display definitions, keypad key definitions, symbol 
definitions, and so on. When you invoke the debugger, those commands are 
executed automatically to tailor your debugging environment. 

Log Files 

You can record in a log file the commands you enter during a debugging session 
and the debugger’s responses to those commands. You can use log files to keep 
track of your debugging efforts, or you can use them as command procedures in 
subsequent debugging sessions. 

Symbol Definitions 

You can define your own symbols to represent lengthy commands, address 
expressions, or values in abbreviated form. 

2.2 Getting Started with the Debugger 

The way you use the debugger depends on several factors: the kind of program 
you are working on, the kinds of errors you are looking for, and your own personal 
style and experience with the debugger. This section explains the following basic 
functions that apply to most situations. 

• Compiling and linking your program to prepare for debugging 

• Establishing the debugging configuration 

• Invoking the debugger 

• Ending a debugging session 
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• Interrupting program execution and aborting debugger commands 

• Entering debugger commands and getting online help 

• Viewing your source code with the TYPE command and in screen mode 

• Controlling program execution with the GO, STEP, and SET BREAK 
commands, and monitoring execution with the SHOW CALLS, SET TRACE, 
and SET WATCH commands 

• Examining and manipulating data with the EXAMINE, DEPOSIT, and 
EVALUATE commands 

• Controlling symbol references with path names and the SET MODULE and 
SET SCOPE commands 

Several examples are language specific. However, the general concepts are 
readily adaptable to all supported languages. 

The sample debugging session in Section 2.3 illustrates how to use some of this 
information to locate an error and correct it. 

2.2.1 Compiling and Linking a Program to Prepare for Debugging 

Before you can use the debugger, you must compile and link the modules 
(compilation units) of your program as explained in this section. The following 
example shows how to compile and link a FORTRAN program, consisting of a 
single compilation unit named FORMS, before using the debugger. 

_ Note- 

The /DEBUG and /NOOPTIMIZE qualifiers are compiler command 
defaults for some languages. These qualifiers are used in the example for 
emphasis. 


$ FORTRAN/DEBUG/NOOPTIMIZE FORMS 
$ LINK/DEBUG FORMS 

The /DEBUG qualifier on the compiler command (FORTRAN in this case) directs 
the compiler to write the symbol i nf ormation associated with FORMS into the 
object module, FORMS.OBJ, in addition to the code and data for the program. 
T his symbol information enables you to use the names of variables and other 
symbols declared in FORMS with debugger commands. If your program has 
several compilation units, you must compile each unit whose symbols you want to 
reference with the /DEBUG qualifier. 

Some compilers optimize the object code to reduce the size of the program or 
to make it run faster. In such cases you should compile your program with the 
/NOOPTIMIZE command qualifier (or equivalent) when preparing for debugging. 
Otherwise, the contents of some program locations might be inconsistent with 
what you would expect from viewing the source code. (After the program has 
been debugged, you will probably want to recompile it without the /NOOPTIMIZE 
qualifier to take advantage of optimization.) 

The /DEBUG qualifier on the LINK command directs the linker to include all 
symbol information that is contained in FORMS. OBJ in the executable image. 
The qualifier also causes the VMS image activator to start the debugger at run 
time. If your program has several object modules, you need to specify those 
modules in the LINK command, for most languages. 
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2.2.2 Establishing the Debugging Configuration 

Before invoking the debugger as explained in Section 2.2.3, check that the 
debugging configuration is appropriate for the kind of program you are going to 
debug. 

You can invoke the debugger in either the default configuration or the 
multiprocess configuration to debug programs that run in either one or severed 
processes, respectively. The configuration depends on the current definition of 
the logical name DBG$PROCESS. Thus, before invoking the debugger, enter the 
DCL command SHOW LOGICAL DBG$PROCESS to determine the definition of 
DBG$PROCESS. 

Most of this chapter covers programs that run in only one process. For such 
programs, DBG$PROCESS either should be undefined, as in the following 
example, or should have the value DEFAULT: 

$ SHOW LOGICAL DBG$PROCESS 

ISHOW-S-NOTRAN, no translation for logical name DBG$PROCESS 

If DBG$PROCESS has the value MULTIPROCESS, and you want to debug a 
program that runs in only one process, enter the following command: 

$ DEFINE DBGSPROCESS DEFAULT 

For more information about multiprocess debugging, see Chapter 10. 

2.2.3 Invoking the Debugger 

After you compile and link your program and establish the appropriate debugging 
configuration, you can then invoke the debugger. To do so, enter the DCL 
command RUN, specifying the executable image of your program as the 
parameter. The following example shows how the debugger identifies itself 
after you invoke it: 

$ RUN FORMS 

VAX DEBUG Version 5.5 

IDEBUG-I-INITIAL, language is FORTRAN, module set to FORMS 
DBG> 

The diagnostic message that is displayed at debugger startup indicates that this 
debugging session is initialized for a FORTRAN program and that the name of 
the main program unit (the module containing the image transfer address) is 
FORMS. The initialization sets up language-dependent debugger parameters. 

At this point, execution is suspended at the beginning of the main program. 

The DBG> prompt, which is displayed whenever the debugger suspends 
execution, indicates that you can now enter debugger commands, as explained in 
Section 2.2.6. 

2.2.4 Ending a Debugging Session 

To end a debugging session and return to DCL level, type EXIT or press Ctrl/Z: 

DBG> EXIT 
$ 

The following message, displayed during a debugging session, indicates that your 
program has completed normally: 

IDEBUG-I-EXITSTATUS, is 'ISYSTEM-S-NORMAL, normal successful completion' 

DBG> 
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If you want to continue debugging after seeing this message, type EXIT and start 
a new debugging session with the DCL RUN command. You could also restart 
execution from within the debugging session with a command such as GO %LINE 
1. However, this can produce unexpected results if, for example, some variables 
have different values from when you first ran the program. 

2.2.5 Interrupting Program Execution and Aborting Debugger Commands 

If your program goes into an infinite loop during a debugging session so that 
the debugger prompt does not reappear, press Ctrl/C. This interrupts program 
execution and returns you to the debugger prompt (pressing Ctrl/C does not end 
the debugging session). For example: 

DBG> GO 


Icwcl 

DBG> 

You can also press Ctrl/C to abort the execution of a debugger command. This is 
useful if a command takes a long time to complete. 

Pressing Ctrl/C when the program is not running or when the debugger is not 
performing an operation has no effect. 

If your program already has a Ctrl/C AST service routine enabled, use the 
SET ABORTJKEY command to assign the debugger’s abort function to another 
Ctrl-key sequence. 

Pressing Ctrl/Y from within a debugging session has the same effect as pressing 
Ctrl/Y du ring the execution of a program. Control is returned to the DCL 
command interpreter ($ prompt). 

2.2.6 Entering Debugger Commands 

You can enter debugger commands any time you see the debugger prompt 
(DBG>). To enter a command, type it at the keyboard and press RETURN. See 
Section 1 of the command dictionary for complete rules on entering debugger 
commands. 

lb obtain online help about debugger commands and specific subjects, proceed as 
follows: 

• lb list the help topics, enter the HELP command. 

• For an explanation of the help system, enter the command HELP HELP. 

For example: 

• To display help about the STEP command, enter the command HELP STEP. 

• To display help about debugger diagnostic messages, enter the command 
HELP MESSAGES. 

Section 2 of the command dictionary explains the general format and severity 
levels of debugger diagnostic messages. To obtain online help about a debugger 
message, use the following general command format: 

HELP MESSAGES message-identifier 
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For example, to display information about the message whose identifier is 
NOSYMBOL, enter the following command: 

DBG> HELP MESSAGES NOSYMBOL 

When you invoke the debugger, a few commonly used command sequences are 
automatically assigned to the keys on the numeric keypad (to the right of the 
main keyboard). Thus, you can perform certain functions either by typing a 
command or by pressing a keypad key. 

The predefined key functions are identified in Figure 2-1. 

Most keypad keys have three predefined functions—DEFAULT, GOLD, and 
BLUE. 

• To enter a key’s DEFAULT function, press the key. 

• To enter its GOLD function, first press and release the PF1 (GOLD) key, and 
then press the key. 

• To enter its BLUE function, first press and release the PF4 (BLUE) key, and 
then press the key. 

In Figure 2-1, the DEFAULT, GOLD, and BLUE functions are listed within each 
key’s outline, from top to bottom, respectively. For example: 

• Pressing keypad key KPO enters the STEP command. 

• Pressing the PF1 key and then KPO enters the STEP/INTO command. 

• Pressing the PF4 key and then KPO enters the STEP/OVER command. 

Normally, keys KP2, KP4, KP6, and KP8 scroll screen displays down, left, 
right, or up, respectively. By putting the keypad in the MOVE, EXPAND, 
or CONTRACT state, indicated in Figure 2—1, you can also use these keys to 
move, expand, or contract displays in four directions. Enter the HELP KEYPAD 
command to display the keypad key definitions. 

You can redefine keypad key functions with the DEFINE/KEY command. 

2.2.7 Displaying Source Code 

The debugger provides two modes for displaying information: noscreen mode and 
screen mode. By default, when you invoke the debugger, you are in noscreen 
mode, but you might find that it is easier to view source code in screen mode. The 
following sections briefly describe both modes. 

2.2.7.1 Noscreen Mode 

Noscreen mode is the default, line-oriented mode of displaying input and output. 
The interactive examples throughout this chapter, excluding Section 2.2.7.2, 
illustrate noscreen mode. 

In noscreen mode, use the TYPE command to display one or more source lines. 
For example, the following command displays line 7 of the module in which 
execution is currently suspended: 

DBG> TYPE 7 
module SWAP_ROUTINES 

7: TEMP := A; 

DBG> 
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Figure 2-1 Keypad Key Functions Predefined by the Debugger—Command Interface 
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The display of source lines is independent of program execution. To display source 
code from a module other than the one in which execution is currently suspended, 
use the TYPE command with a path name to specify the module. For example, 
the following command displays lines 16 to 21 of module TEST: 

DBG> TYPE TEST\16:21 

Path names are discussed in more detail in Section 2.2.8.1, in conjunction with 
the STEP command. 

You can also use the EXAMINE/SOURCE command to display the source line for 
a routine or any other program location that is associated with an instruction. 

Note that the debugger also displays source lines automatically when it suspends 
execution at a breakpoint or watchpoint or after a STEP command, or when a 
tracepoint is triggered (see Section 2.2.8). 

After displaying source lines at various locations in your program, you can 
redisplay the location at which execution is currently suspended by pressing 
keypad key KP5. 

If the debugger cannot locate source lines for display, it issues a diagnostic 
message. Source lines might not be available for a variety of reasons. For 
example: 

• Execution is suspended within a module that was compiled or linked without 
the /DEBUG qualifier. 

• Execution is suspended within a system or shareable image routine for which 
no source code is available. 

• The source file was moved to a different directory after it was compiled (the 
location of source files is embedded in the object modules). In this case, use 
the SET SOURCE command to specify the new location. 

• The module might need to be "set" with the SET MODULE command. 
Module setting is explained in Section 2.2.10.1. 

To invoke noscreen mode from screen mode, press the keypad key sequence 
GOLD-PF3 (or type SET MODE NOSCREEN). Note that you can use the TYPE 
and EXAMINE/SOURCE commands in screen mode as well as noscreen mode. 

2.2.7.2 Screen Mode 

Screen mode provides the easiest way to view your source code. To invoke screen 
mode, press the PF3 key (or type SET MODE SCREEN). In screen mode, by 
default the debugger splits the screen into three displays named SRC, OUT, and 
PROMPT, as illustrated in Figure 2-2. 
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Figure 2-2 Default Screen Mode Display Configuration 



The SRC display shows the source code of the module in which execution is 
currently suspended. An arrow in the left column points to the source line 
corresponding to the current value of the program counter (PC). The PC is a VAX 
register that contains the memory address of the instruction to be executed next. 
The line numbers, which are assigned by the compiler, match those in a listing 
file. As you execute the program, the arrow moves down and the source code is 
scrolled vertically to center the arrow in the display. 

The OUT display captures the debugger’s output in response to the commands 
that you enter. The PROMPT display shows the debugger prompt, your input (the 
commands that you enter), debugger diagnostic messages, and program output. 

Both SRC and OUT are scrollable so you can see whatever information might 
scroll beyond the display window’s edge. Use keypad key KP3 to select the 
display to be scrolled (by default, SRC is scrolled). Use keypad key KP8 to 
scroll up and keypad key KP2 to scroll down. Scrolling a display does not affect 
program execution. 

In screen mode, if the debugger cannot locate source lines for the routine in 
which execution is currently suspended, it tries to display source lines in the 
next routine down on the call stack for which source lines are available. If the 
debugger can display source lines for such a routine, it issues the following 
message: 

%DEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC. 

Displaying source in a caller of the current routine. 

DBG> 

In such cases, the arrow in the SRC display identifies the line that contains code 
following the call statement in the calling routine. 
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2.2.8 Controlling and Monitoring Program Execution 

This section explains how to perform the following tasks: 

• Start and resume program execution 

• Execute the program to the next source line, instruction, or other step unit 

• Determine where execution is currently suspended 

• Use breakpoints to suspend program execution at points of interest 

• Use tracepoints to trace the execution path of your program through specified 
locations 

• Use watchpoints to monitor changes in the values of variables 

With this information you can pick program locations where you can then test 
and manipulate the contents of variables as described in Section 2.2.9. 

2.2.8.1 Starting or Resuming Program Execution 

Use the GO command to start or resume program execution. 

After it is started with the GO command, program execution continues until one 
of the following events occurs: 

• The program completes execution 

• A breakpoint is reached 

• A watchpoint is activated 

• An exception is signaled 

• You press Ctrl/C 

With most programming languages, when you invoke the debugger, execution is 
initially suspended directly at the beginning of the main program. Entering a 
GO command at this point quickly enables you to test for an infinite loop or an 
exception. 

If an infinite loop occurs during execution, the program does not terminate, so the 
debugger prompt does not reappear. To obtain the prompt, interrupt execution 
by pressing Ctrl/C (see Section 2.2.5). If you are using screen mode, the pointer 
in the source display indicates where execution stopped. You can also use the 
SHOW CALLS command to identify the currently active routine calls on the call 
stack (see Section 2.2.8.3). 

If an exception that is not handled by your program is signaled, the debugger 
interrupts execution at that point so that you can enter commands. You can then 
look at the source display and a SHOW CALLS display to find where execution is 
suspended. 

The most common use of the GO command is in conjunction with breakpoints, 
tracepoints, and watchpoints, as described in Section 2.2.8.4, Section 2.2.8.5, 
and Section 2.2.8.6, respectively. If you set a breakpoint in the path of execution 
and then enter the GO command, execution is suspended at that breakpoint. 
Similarly, if you set a tracepoint, execution is monitored through that tracepoint. 
And if you set a watchpoint, execution is suspended when the value of the 
"watched" variable changes. 
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2.2.8.2 Executing the Program by Step Unit 

Use the STEP command to execute the program one or more step units at a time. 

By default, a step unit is one line of source code. In the following example, the 
STEP command executes one line, reports the action ("stepped to . .. "), and 
displays the line number (27) and source code of the line to be executed next: 

DBG> STEP 

stepped to TEST\COUNT\%LINE 27 
27: X := X + 1; 

DBG> 

Execution is now suspended at the first machine code instruction for line 27 of 
module TEST. Line 27 is in COUNT, a routine within module TEST. 

When displaying a program symbol (for example, a line number, routine name, or 
variable name), the debugger always uses a path name. A path name consists 
of the symbol plus a prefix that identifies the symbol’s location. In the preceding 
example, the path name is TEST\ COUNT\ %LINE 27. The leftmost element of 
a path name is the module name. Moving toward the right, the path name lists 
any successively nested routines and blocks that enclose the symbol. A backslash 
character (\ ) is used to separate elements (except when the language is Ada, 
where a period is used, to parallel Ada syntax). 

A path name uniquely identifies a symbol of your program to the debugger. In 
general, you need to use path names in commands only if the debugger cannot 
resolve a symbol ambiguity in your program (see Section 2.2.10). Usually the 
debugger can determine the symbol you mean from its context. 

When using the STEP command, note that only those source lines for which code 
instructions were generated by the compiler are recognized as executable lines by 
the debugger. The debugger skips over any other lines—for example, comment 
lines. 

You can specify different stepping modes, such as stepping by instruction rather 
than by line (SET STEP INSTRUCTION). Also, by default, the debugger steps 
"over" called routines—execution is not suspended within a called routine, 
although the routine is executed. By entering the SET STEP INTO command, 
you direct the debugger to suspend execution within called routines as well as 
within the routine in which execution is currently suspended (SET STEP OVER 
is the default mode). 

2.2.8.3 Determining Where Execution Is Suspended 

The SHOW CALLS command is useful when you are unsure where execution is 
suspended during a debugging session (for example, after a Ctrl/C interruption). 

The command displays a traceback that lists the sequence of calls leading to 
the routine in which execution is suspended. For each routine (beginning with 
the one in which execution is suspended), the debugger displays the following 
information: 

• The name of the module that contains the routine 

• The name of the routine 

• The line number at which the call was made (or at which execution is 
suspended, in the case of the current routine) 

• The corresponding PC values (the relative PC address from the beginning of 
the routine and the absolute PC address of the program) 
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For example: 

DBG> SHOW CALLS 


module name 

routine name 

line 

rel PC 

abs PC 

*TEST 

PRODUCT 

18 

00000009 

0000063C 

*TEST 

COUNT 

47 

00000009 

00000647 

*MY PROG 

DBG> 

MY PROG 

21 

0000000D 

00000653 


This example indicates that execution is suspended at line 18 of routine 
PRODUCT (in module TEST), which was called from line 47 of routine COUNT 
(in module TEST), which was called from line 21 of routine MYJPROG (in module 
MYJPROG). 

2.2.8.4 Suspending Program Execution with Breakpoints 

The SET BREAK command enables you to select locations at which to suspend 
program execution (breakpoints). You can then enter commands to check the call 
stack, examine the current values of variables, and so on. You resume execution 
from a breakpoint with the GO or STEP commands. 

The following example shows a typical use of the SET BREAK command: 

DBG> SET BREAK COUNT 
DBG> GO 

break at routine PR0G2\C0UNT 

54: procedure COUNT(X,Y:INTEGER); 

DBG> 

In the example, the SET BREAK command sets a breakpoint on routine COUNT 
(at the beginning of the routine's code); the GO command starts execution; 
when routine COUNT is encountered, execution is suspended, the debugger 
announces that the breakpoint at COUNT has been reached ("break at . . . "), 
displays the source line (54) at which execution is suspended, and prompts for 
another command. At this breakpoint, you could use the STEP command to step 
through routine COUNT and then use the EXAMINE command (discussed in 
Section 2.2.9.1) to check on the values of X and Y. 

When using the SET BREAK command, you can specify program locations using 
various kinds of address expressions (for example, line numbers, routine 
names, memory addresses, byte offsets). With high level languages, you typically 
use routine names, labels, or line numbers, possibly with path names to ensure 
uniqueness. 

Routine names and labels should be specified as they appear in the source code. 
Line numbers can be derived from either a source code display or a listing file. 
When specifying a line number, use the prefix %LINE. Otherwise the debugger 
interprets the line number as a memory location. For example, the next command 
sets a breakpoint at line 41 of the module in which execution is suspended. The 
breakpoint causes the debugger to suspend further execution when the PC value 
is at the beginning of line 41. 

DBG> SET BREAK %LINE 41 
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Note that you can set breakpoints only on lines that resulted in machine code 
instructions. The debugger warns you if you try to do otherwise (for example on 
a comment line). To pick a line number in a module other than the one in which 
execution is suspended, you must specify the module’s name in a path name. For 
example: 

DBG> SET BREAK SCREEN_IO\%LINE 58 

You can also use the SET BREAK command with a qualifier, but no parameter, to 
break on every line, or on every CALL instruction, and so on. For example: 

DBG> SET BREAK/LINE 
DBG> SET BREAK/CALL 

You can set breakpoints on events, such as exceptions, or state transitions in 
tasking programs. 

You can conditionalize a breakpoint (with a "WHEN" clause) or specify that a list 
of commands be executed at the breakpoint (with a "DO" clause). 

To display the currently active breakpoints, enter the SHOW BREAK command. 

To cancel a breakpoint, enter the CANCEL BREAK command, specifying the 
program location exactly as you did when setting the breakpoint. CANCEL 
BREAK/ALL cancels all breakpoints. 

2.2.8.5 Tracing Program Execution with Tracepoints 

The SET TRACE command enables you to select locations for tracing the 
execution of your program (tracepoints), without stopping its execution. After 
setting a tracepoint, you can start execution with the GO command and then 
monitor the path of execution, checking for unexpected behavior. By setting a 
tracepoint on a routine, you can also monitor the number of times it is called. 

As with breakpoints, every time a tracepoint is reached, the debugger issues a 
message and displays the source line. But the program continues executing, and 
the debugger prompt is not displayed. For example: 

DBG> SET TRACE COUNT 
DBG> GO 

trace at routine PR0G2\C0UNT 

54: procedure COUNT(X,Y:INTEGER); 


This is the only difference between a breakpoint and a tracepoint. When using 
the SET TRACE command, you specify address expressions, qualifiers, and 
optional clauses exactly as with the SET BREAK command. 

2.2.8.6 Monitoring Changes in Variables with Watchpoints 

The SET WATCH command enables you to specify program variables that the 
debugger monitors as your program executes. This process is called setting 
watchpoints. If the program modifies the value of a "watched" variable, the 
debugger suspends execution and displays information. The debugger monitors 
watchpoints continuously during program execution. (Note that the SET WATCH 
command can also be used to monitor arbitrary program locations, not just 
variables.) 
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To set a watchpoint on a variable, specify the variable's name with the SET 
WATCH command. For example, the following command sets a watchpoint on the 
variable TOTAL: 

DBG> SET WATCH TOTAL 

Subsequently, every time the program modifies the value of TOTAL, the 
watchpoint is triggered. 

The next example shows what happens when your program modifies the contents 
of a watched variable. 

DBG> SET WATCH TOTAL 
DBG> GO 


watch of SCREEN_I0\TOTAL at SCREEN_IO\%LINE 13 
13: TOTAL := TOTAL + 1; 

old value: 16 
new value: 17 

break at SCREEN_IO\%LINE 14 
14: POP(TOTAL); 

DBG> 

In this example, a watchpoint is set on the variable TOTAL and execution is 
started. When the value of TOTAL changes, execution is suspended. The 
debugger announces the event ("watch of. . . "), identifying where TOTAL 
changed (the beginning of line 13) and the associated source line. The debugger 
then displays the old and new values and announces that execution has been 
suspended at the beginning of the next line (14). Finally, the debugger prompts 
for another command. Note that when a change in a variable occurs at a point 
other than the beginning of a source line, the debugger gives the line number 
plus the byte offset from the beginning of the line. 

The technique previously described for setting watchpoints always applies to 
static variables. A static variable is associated with the same memory address 
throughout program execution. 

A variable that is allocated on the stack or in a register (a nonstatic variable) 
exists only when its defining routine is active (on the call stack). If you try to set 
a watchpoint on a nonstatic variable when its defining routine is not active, the 
debugger issues a warning: 

DBG> SET WATCH Y 

%DEBUG-W-SYMNOTACT, nonstatic variable 'V is not active 
DBG> 

A convenient technique for setting a watchpoint on a nonstatic variable is to 
set a tracepoint on the defining routine, also specifying a DO clause to set the 
watchpoint whenever execution reaches the tracepoint. In the following example, 
a watchpoint is set on the nonstatic variable Y in routine ROUT3. After the 
tracepoint is triggered, the WPTTRACE message indicates that the nonstatic 
watchpoint is set. And the watchpoint is triggered when the value of Y changes: 
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DBG> SET TRACE/NOSOURCE R0UT3 DO (SET WATCH Y) 
DBG> GO 


trace at routine MOD4\ROUT3 

IDEBUG-I-WPTTRACE , nonstatic watchpoint, tracing every 
instruction 


watch of MOD4\ROUT3\Y at MOD4\ROUT3\%LINE 16 
16: Y := 4 

old value: 3 

new value: 4 

break at MOD4\ROUT3\%LINE 17 
17: SWAP(X,Y); 

DBG> 

When execution returns to the calling routine, the nonstatic variable is no 
longer active, so the debugger automatically cancels the watchpoint and issues a 
message to that effect. 

2.2.9 Examining and Manipulating Program Data 

This section explains how to use the EXAMINE, DEPOSIT, and EVALUATE 
commands to display and modify the contents of variables and evaluate 
expressions. Note that before you can examine or deposit into a nonstatic 
variable, as defined in Section 2.2.8.6, its defining routine must be active (on the 
call stack). 

2.2.9.1 Displaying the Value of a Variable 

To display the current value of a variable, use the EXAMINE command. It has 
the following form: 

EXAMINE variable-name 

The debugger recognizes the compiler-generated data type of the variable you 
specify and retrieves and formats the data accordingly. The following examples 
show some uses of the EXAMINE command. 

Examine a string variable: 

DBG> EXAMINE EMPLOYEE_NAME 
PAYROLL\EMPLOYEE_NAME: "Peter C. Lombardi" 

DBG> 

Examine three integer variables: 

DBG> EXAMINE WIDTH, LENGTH, AREA 

SIZEXWIDTH: 4 

SIZE\LENGTH: 7 

SIZEYAREA: 28 

DBG> 
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Examine a two-dimensional array of real numbers (three per dimension): 

DBG> EXAMINE REAL_ARRAY 
P R0G2\REAL_ARRAY 


0,1): 

27.01000 

0,2): 

31.00000 

(1,3): 

12.48000 

(2,1): 

15.08000 

(2,2): 

22.30000 

(2,3): 

18.73000 


DBG> 

Examine element 4 of a one-dimensional array of characters: 

DBG> EXAMINE CHAR_ARRAY(4) 

PR0G2\CHAR_ARRAY(4): 'm' 

DBG> 

Examine a record variable (COBOL example): 

DBG> EXAMINE PART 
INVENTORY\PART: 

ITEM: "WF-1247" 

PRICE: 49.95 

IN_STOCK: 24 

DBG> 

Examine a record component (COBOL example): 

DBG> EXAMINE IN_STOCK OF PART 
INVENTORY\IN-STOCK of PART: 

IN_STOCK: 24 

DBG> 

Note that the EXAMINE command can be used with any kind of address 
expression (not just a variable name) to display the contents of a program 
location. The debugger associates certain default data types with untyped 
locations. You can override the defaults for typed and untyped locations if you 
want the data interpreted and displayed in some other data format. 

2.2.9.2 Assigning a Value to a Variable 

To assign a new value to a variable, use the DEPOSIT command. It has the 
following form: 

DEPOSIT variable-name = value 

The DEPOSIT command is like an assignment statement in most programming 
languages. 

In the following examples, the DEPOSIT command assigns new values to 
different variables. The debugger checks that the value assigned, which can 
be a language expression, is consistent with the data type and dimensional 
constraints of the variable. 

Deposit a string value (it must be enclosed in quotation marks (") or apostrophes 

('): 


DBG> DEPOSIT PART_NUMBER = "WG-7619.3-84" 
Deposit an integer expression: 

DBG> DEPOSIT WIDTH = CURRENT WIDTH + 10 
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Deposit element 12 of an array of characters (you cannot deposit an entire array 
aggregate with a single DEPOSIT command, only an element): 

DBG> DEPOSIT C_ARRAY(12) := 'K' 

Deposit a record component (you cannot deposit an entire record aggregate with a 
single DEPOSIT command, only a component): 

DBG> DEPOSIT EMPLOYEE.ZIPCODE = 02172 

Deposit an out-of-bounds value (X was declared as a positive integer): 

DBG> DEPOSIT X = -14 

IDEBUG-I-IVALOUTBNDS, value assigned is out of bounds 
at or near DEPOSIT 

As with the EXAMINE command, you can specify any kind of address expression 
(not just a variable name) with the DEPOSIT command. You can override the 
defaults for typed and untyped locations if you want the data interpreted in some 
other data format. 

2.2.9.3 Evaluating Language Expressions 

To evaluate a language expression, use the EVALUATE command. It has the 
following form: 

EVALUATE language-expression 

The debugger recognizes the operators and expression syntax of the currently 
set language. In the following example, the value 45 is assigned to the integer 
variable WIDTH; the EVALUATE command then obtains the sum of the current 
value of WIDTH and 7: 

DBG> DEPOSIT WIDTH := 45 
DBG> EVALUATE WIDTH + 7 
52 

DBG> 

In the next example, the values TRUE and FALSE are assigned to the Boolean 
variables WILLING and ABLE, respectively; the EVALUATE command then 
obtains the logical conjunction of these values: 

DBG> DEPOSIT WILLING := TRUE 
DBG> DEPOSIT ABLE := FALSE 
DBG> EVALUATE WILLING AND ABLE 
False 
DBG> 

2.2.10 Controlling Access to Symbols in Your Program 

To have full access to the symbols that are associated with your program (variable 
names, routine names, source code, line numbers, and so on), you must compile 
and link the program using the /DEBUG qualifier, as explained in Section 2.2.1. 

Under these conditions, the way in which the debugger handles these symbols 
is transparent to you, in most cases. However, the following two areas might 
require action: 

• Setting and canceling modules 

• Resolving symbol ambiguities 
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2.2.10.1 Setting and Canceling Modules 

To facilitate symbol searches, the debugger loads symbol information from the 
executable image into a run-time symbol table (RST), where that information can 
be accessed efficiently Unless symbol information is in the RST, the debugger 
does not recognize or properly interpret the associated symbols. 

Because the RST takes up memory, the debugger loads it dynamically, 
anticipating what symbols you might want to reference in the course of program 
execution. The loading process is called module setting, because all symbol 
information for a given module is loaded into the RST at one time. 

At debugger startup, only the module containing the image transfer address 
is set. Subsequently, whenever execution of the program is interrupted, the 
debugger sets the module that contains the routine in which execution is 
suspended. This enables you to reference the symbols that should be visible 
at that location. 

If you try to reference a symbol in a module that has not been set, the debugger 
warns you that the symbol is not in the RST. For example: 

DBG> EXAMINE K 

IDEBUG-W-NOSYMBOL, symbol 'K' is not in symbol table 
DBG> 

You must then use the SET MODULE command to set the module containing 
that symbol explicitly: 

DBG> SET MODULE M0D3 
DBG> EXAMINE K 
MOD3\ROUT2\K: 26 
DBG> 

The SHOW MODULE command lists the modules of your program and identifies 
which modules are set. 

Note that dynamic module setting can slow the debugger down as more and more 
modules are set. If performance becomes a problem, you can use the CANCEL 
MODULE command to reduce the number of set modules, or you can disable 
dynamic module setting by entering the SET MODE NODYNAMIC command 
(SET MODE DYNAMIC enables dynamic module setting). 

2.2.10.2 Resolving Symbol Ambiguities 

Symbol ambiguities can occur when a symbol (for example, a variable name X) is 
defined in more than one routine or other program unit. 

In most cases, the debugger resolves symbol ambiguities automatically. First 
it uses the scope and visibility rules of the currently set language. In addition, 
because the debugger permits you to specify symbols in arbitrary modules (to set 
breakpoints and so on), the debugger uses the ordering of routine calls on the call 
stack to resolve symbol ambiguities. 

If the debugger cannot resolve a symbol ambiguity, it issues a message. For 
example: 

DBG> EXAMINE Y 

%DEBUG-W-NOUNIQUE, symbol 'Y' is not unique 
DBG> 
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You can then use a path name prefix to uniquely specify a declaration of the 
given symbol. First, use the SHOW SYMBOL command to identify all path 
names associated with the given symbol (corresponding to all declarations of that 
symbol) that are currently loaded in the RST. Then use the desired path name 
prefix when referencing the symbol. For example: 

DBG> SHOW SYMBOL Y 

data MOD7\ROUT3\BLOCKl\Y 

data MOD4\ROUT2\Y 

DBG> EXAMINE MOD4\ROUT2\Y 

MOD4\ROUT2\Y: 12 

DBG> 

If you need to refer to a particular declaration of Y repeatedly, use the SET 
SCOPE command to establish a new default scope for symbol lookup. Then, 
references to Y without a path name prefix specify the declaration of Y that is 
visible in the new scope. For example: 

DBG> SET SCOPE MOD4\ROUT2 
DBG> EXAMINE Y 
MOD4\ROUT2\Y: 12 
DBG> 

To display the current scope for symbol lookup, use the SHOW SCOPE command. 
To restore the default scope, use the CANCEL SCOPE command. 

2.3 A Sample Debugging Session 

This section walks you through a debugging session with a simple FORTRAN 
program which contains a logic error (see Example 2-1). Compiler-assigned line 
numbers have been added in the example so that you can identify the source lines 
referenced in the discussion. 


Example 2-1 Sample Program SQUARES 

1: INTEGER INARR(20), OUTARR(20) 

2: C 

3: C —Read the input array from the data file. 

4: OPEN(UNIT=8, FILE*'DATAFILE.DAT', STATUS*'OLD') 

5: READ(8,*) N, (INARR(I), 1=1,N) 

6: C 

7: C —Square all non-zero elements and store in OUTARR. 
8: K = 0 

9: DO 10 I = 1, N 

10: IF(INARR(I) .NE. 0) THEN 

11: OUTARR(K) = INARR(I)**2 

12: ENDIF 

13: 10 CONTINUE 

14: C 

15: C —Print the squared output values. Then stop. 

16: PRINT 20, K 

17: 20 FORMAT(' Number of non-zero elements is',14) 

18: DO 40 I = 1, K 

19: PRINT 30, I, OUTARR(I) 

20: 30 FORMAT!' Element',14,' has value',16) 

21: 40 CONTINUE 

22: END 


The program, called SQUARES, performs the following functions: 

1. Reads a sequence of integer numbers from a data file and saves these 
numbers in the array INARR (lines 4 and 5). 
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2. Enters a loop in which it copies the square of each nonzero integer into 
another array OUTARR (lines 8 through 13). 

3. Prints the number of nonzero elements in the original sequence and the 
square of each such element (lines 16 through 21). 

When you run SQUARES, it produces the following output, regardless of the 
number of nonzero elements in the data file: 

$ RUN SQUARES 

Number of non-zero elements is 0 

The error in the program is that variable K, which keeps track of the current 
index into OUTARR, is not incremented in the loop on lines 9 through 13. The 
statement K = K + 1 should be inserted just before line 11. 

Example 2-2 shows how to compile, link, and run the program to invoke the 
debugger, and then how to use the debugger to find the error. Comments, keyed 
to the callouts, follow the example. 


Example 2-2 Sample Debugging Session Using Program SQUARES 

$ FORTRAN/DEBUG/NOOPTIMIZE SQUARES O 
$ LINK/DEBUG SQUARES © 

$ SHOW LOGICAL DBG$PROCESS © 

%SHOW-S-NOTRAN, no translation for logical name DBG$PROCESS 
$ RUN SQUARES © 

VAX DEBUG Version 5.5 

%DEBUG-I-INITIAL, language is FORTRAN, module set to SQUARES$MAIN 
DBG> STEP 4 © 

stepped to SQUARES$MAIN\%LINE 9 
9: DO 10 I = 1, N 

DBG> EXAMINE N,K © 

SQUARES$MAIN\N: 9 

SQUARES$MAIN\K: 0 

DBG> STEP 2 © 

stepped to SQUARES$MAIN\%LINE 11 

11: OUTARR(K) = INARR(I)**2 

DBG> EXAMINE I,K © 

SQUARES$MAIN\I: 1 

SQUARES$MAIN\K: 0 

DBG> DEPOSIT K = 1 © 

DBG> SET TRACE/SILENT %LINE 11 DO (DEPOSIT K = K + 1) ® 

DBG> GO © 

Number of non-zero elements is 4 
Element 1 has value 16 

Element 2 has value 36 

Element 3 has value 9 

Element 4 has value 49 

%DEBUG-I-EXITSTATUS, is 'SYSTEM-S-NORMAL, normal successful completion' 
DBG> EXIT © 

$ EDIT SQUARES.FOR © 


10: IF(INARR(I) .NE. 0) THEN 

11: K = K + 1 

12: OUTARR(K) = INARR(I)**2 

13: ENDIF 


(continued on next page) 
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Example 2-2 (Cont.) Sample Debugging Session Using Program SQUARES 


$ FORTRAN/DEBUG/NOOPTIMIZE SQUARES © 
$ LINK/DEBUG SQUARES 
$ RUN SQUARES 


DBG> SET BREAK %LINE 12 DO (EXAMINE I,K) © 
DBG> GO © 


SQUARES$MAIN\I: 1 
SQUARES$MAIN\K: 1 
DBG> GO 

SQUARES$MAIN\I: 2 
SQUARES$MAIN\K: 2 
DBG> GO 

SQUARES$MAIN\I: 4 
SQUARES$MAIN\K: 3 
DBG> 


The following comments apply to the callouts in Example 2-2. Example 2-1 

shows the program that is being debugged. 

O The /DEBUG qualifier on the FORTRAN command directs the compiler 
to write the symbol information associated with SQUARES into the object 
module, SQUARES.OBJ, in addition to the code and data for the program. 

The /NOOPTIMIZE qualifier disables optimization by the FORTRAN 
compiler, to ensure that the executable code match the source code of the 
program. Debugging optimized code can be confusing because the contents 
of some program locations might be inconsistent with what you would expect 
from viewing the source code. 

© The /DEBUG qualifier on the LINK command causes the linker to include all 
symbol information that is contained in SQUARES.OBJ in the executable 
image. The qualifier also causes the VMS image activator to start the 
debugger at run time. 

© The debugger can be invoked in either the default configuration or the 
multiprocess configuration, depending on the definition of the logical name 
DBG$PROCESS. In this example, the SHOW LOGICAL DBG$PROCESS 
command shows that DBG$PROCESS is undefined, indicating that the 
default configuration is in effect. This is the correct configuration for a 
program like SQUARES that runs in only one process. 

© The RUN command invokes the debugger (if you have used the /DEBUG 
qualifier with the LINK command). 


2-23 





Introduction to the Debugger: Command Interface 
2.3 A Sample Debugging Session 


When the debugger is invoked, it displays an informational message and the 
debugger prompt, DBG>. You can now enter debugger commands. Execution 
is initially suspended at the start of the main program unit (line 1 of program 
SQUARES, in this example). 

© You decide to test the values of variables N and K after the READ statement 
has been executed and the value 0 has been assigned to K. 

The command STEP 4 executes 4 source lines of the program. Execution is 
now suspended at line 9. Note that the STEP command ignores source lines 
that do not result in executable code; also, by default, the debugger identifies 
the source line at which execution is suspended. 

© The command EXAMINE N, K displays the current values of N and K. Their 
values are correct at this point in the execution of the program. 

Q The command STEP 2 executes the program into the loop that copies and 
squares all nonzero elements of INARR into OUTARR. 

© The command EXAMINE I,K displays the current values of I and K. 

I has the expected value, 1. But K has the value 0 instead of 1, which is 
the expected value. Now you can see the error in the program: K should be 
incremented in the loop just before it is used in line 11. 

© The DEPOSIT command assigns K the value it should have now: 1. 

© The SET TRACE command is now used to patch the program so that the 
value of K is incremented automatically in the loop. The command sets a 
tracepoint that triggers every time execution reaches line 11: 

• The /SILENT qualifier suppresses the "trace at" message that would 
otherwise appear each time line 11 is executed. 

• The DO clause issues the DEPOSIT K = K + 1 command every time the 
tracepoint is triggered. 

© To test the patch, the GO command starts execution from the current location. 

The program output shows that the patched program works properly. The 
EXITSTATUS diagnostic message shows that the program executed to 
completion. 

© The EXIT command ends the debugging session, returning control to DCL 
level. 

© The source file is edited to add K = K + 1 after line 10, as shown. (Compiler- 
assigned line numbers have been added to clarify the example.) 

© The program is compiled, linked, and executed again under debugger control, 
to check that it runs correctly. 

© The SET BREAK command sets a breakpoint that triggers every time line 12 
is executed. The DO clause displays the values of I and K automatically when 
the breakpoint triggers. 

© The GO command starts execution. 

At the first breakpoint, the value of K is 1, indicating that the program is 
running correctly so far. Each additional GO command shows the current 
values of I and K. After two GO commands, K is now 3, as expected, but 
note that I is 4. The reason is that one of the INARR elements was zero so 
that lines 11 and 12 were not executed (and K was not incremented) for that 
iteration of the DO loop. This confirms that the program is running correctly. 
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2.4 Debugger Command Summary 

The following sections list all the debugger commands and any related DCL 
commands in functional groupings, along with brief descriptions. During a 
debugging session, you can get online help on all debugger commands and their 
qualifiers by typing HELP. 

2.4.1 Starting and Ending a Debugging Session 

The following commands are used to start, interrupt, and end a debugging 
session: 


2.4.2 


RUN 1 

Invokes the debugger if LINK/DEBUG was 
used 

RUN/tNOlDEBUG 1 

Controls whether the debugger is invoked 
when the program is executed 

EXIT, Ctrl/Z 

Ends a debugging session, executing all exit 
handlers 

QUIT 

Ends a debugging session without executing 
any exit handlers declared in the program 

Ctrl/C 

Aborts program execution or a debugger 
command without interrupting the debugging 
session 

(SET,SHOW) ABORT.KEY 

(Assigns, identifies) the default Ctrl/C abort 
function to another Ctrl-key sequence, 
identifies the Ctrl-key sequence currently 
defined for the abort function 

Ctrl/Y-DEBUG 1 

Interrupts a program that is running without 
debugger control and invokes the debugger 

ATTACH 

Passes control of your terminal from the 
current process to another process 

SPAWN 

Creates a subprocess, enabling you to execute 
DCL commands without ending a debugging 
session or losing your debugging context 

1 This is a DCL command, not a debugger command. 

Controlling and Monitoring Program Execution 

The following commands are used to control and monitor program execution: 

GO 

Starts or resumes program execution 

STEP 

Executes the program up to the next line, 
instruction, or specified instruction 

(SET,SHOW) STEP 

(Establishes, displays) the default qualifiers 
for the STEP command 

(SET,SHOW,CANCEL) BREAK 

(Sets, displays, cancels) breakpoints 

(SET,SHOW,CANCEL) TRACE 

(Sets, displays, cancels) tracepoints 

(SET,SHOW,CANCEL) WATCH 

(Sets, displays, cancels) watchpoints 

SHOW CALLS 

Identifies the currently active routine calls 

SHOW STACK 

Gives additional information about the 
currently active routine calls 

CALL 

Calls a routine 
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2.4.3 Examining and Manipulating Data 

The following commands are used to examine and manipulate data: 

EXAMINE Displays the value of a variable or the 

contents of a program location 

SET MODE [NO]OPERANDS Controls whether the address and contents of 

the instruction operands are displayed when 
you examine an instruction 

DEPOSIT Changes the value of a variable or the 

contents of a program location 

EVALUATE Evaluates a language or address expression 


2.4.4 Controlling Type Selection and Radix 

The following commands are used to control type selection and radix: 

(SET,SHOW,CANCEL) RADIX (Establishes, displays, restores) the radix for 

data entry and display 

(SET,SHOW,CANCEL) TYPE (Establishes, displays, restores) the type for 

program locations that are not associated with 
a compiler generated type 

SET MODE [NO]G_FLOAT Controls whether double-precision floating¬ 

point constants are interpreted as GJFLOAT 
or DJFLOAT 


2.4.5 Controlling Symbol Lookup and Symbolization 

The following commands are used to control symbol lookup and symbolization: 


SHOW SYMBOL 

(SET,SHOW,CANCEL) MODULE 

(SET,SHOW,CANCEL) IMAGE 

SET MODE [NOIDYNAMIC 

(SET,SHOW,CANCEL) SCOPE 

SYMBOLIZE 

SET MODE [NOILINE 

SET MODE [NOISYMBOLIC 


Displays symbols in your program 

Sets a module by loading its symbol 
information into the debugger's symbol table, 
identifies, cancels a set module 

Sets a shareable image by loading data 
structures into the debugger's symbol table, 
identifies, cancels a set image 

Controls whether or not modules and 
shareable images are set automatically when 
the debugger interrupts execution 

(Establishes, displays, restores) the scope for 
symbol lookup 

Converts a memory address to a symbolic 
address expression 

Controls whether program locations are 
displayed in terms of line numbers or routine- 
name + byte offset 

Controls whether program locations are 
displayed symbolically or in terms of numeric 
addresses 
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2.4.6 Displaying Source Code 

The following commands are used 
TYPE 

EXAMINE/SOURCE 
SEARCH 

(SET,SHOW) SEARCH 
SET STEP [NOISOURCE 

(SET,SHOW) MARGINS 
(SET,SHOW,CANCEL) SOURCE 
(SET,SHOW) MAX_SOURCE_FII 

2.4.7 Using Screen Mode 

The following commands are u 

SET MODE [NOJSCREEN 
DISPLAY 
SCROLL 
EXPAND 
MOVE 

(SHOW,CANCEL) DISPLAY 
(SET,SHOW,CANCEL) WINDOW 

SELECT 
SHOW SELECT 

SAVE 

EXTRACT 

(SET,SHOW) TERMINAL 

SET MODE [NO]SCROLL 
Ctrl/W 

DISPLAY/REFRESH 


to control the display of source code: 

Displays lines of source code 

Displays the source code at the location 
specified by the address expression 

Searches the source code for the specified 
string 

(Establishes, displays) the default qualifiers 
for the SEARCH command 

Enables/disables the display of source code 
after a STEP command has been executed or 
at a breakpoint, tracepoint, or watchpoint 

(Establishes, displays) the left and right 
margin settings for displaying source code 

(Creates, displays, cancels) a source directory 
search list 

(Establishes, displays) the maximum number 
of source files that can be kept open at one 
time (but does not limit the number of source 
files that can be opened) 


to control screen mode and screen displays: 

Enables/disables screen mode 

Creates or modifies a display 

Scrolls a display 

Expands or contracts a display 

Moves a display across the screen 

(Identifies, deletes) a display 

(Creates, identifies, deletes) a window 
definition 

Selects a display for a display attribute 

Identifies the displays selected for each of the 
display attributes 

Saves the current contents of a display into 
another display 

Saves a display or the current screen state 
into a file 

(Establishes, displays) the terminal screen 
height and width that the debugger uses when 
it formats displays and other output 

Controls whether an output display is updated 
line by line or once per command 

Refreshes the screen 
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2.4.8 Editing Source Code 

The following commands are used to control source editing from a debugging 
session: 

EDIT Invokes an editor during a debugging session 

(SET,SHOW) EDITOR (Establishes, identifies) the editor invoked by 

the EDIT command 


2.4.9 Defining Symbols 

The following commands are used to define and delete symbols for addresses, 
commands, or values: 

DEFINE Defines a symbol as an address, command, or 

value 


DELETE 

(SET,SHOW) DEFINE 
SHOW SYMBOL/DEFINED 


Deletes symbol definitions 

(Establishes, displays) the default qualifier for 
the DEFINE command 

Identifies symbols that have been defined with 
the DEFINE command 


2.4.10 Using Keypad Mode 

The following commands are used to control keypad mode and key definitions: 

SET MODE [NO]KEYPAD Enables/disables keypad mode 

DEFINE/KEY Creates key definitions 

DELETE/KEY Deletes key definitions 

SET KEY Establishes the key definition state 

SHOW KEY Displays key definitions 

2.4.11 Using Command Procedures, Log Files, and Initialization Files 

The following commands are used with command procedures and log files: 


@file-spec 

(SET,SHOW) ATSIGN 

DECLARE 

(SET,SHOW) LOG 
SET OUTPUT [NO]LOG 

SET OUTPUT [NO]SCREEN_LOG 

SET OUTPUT [NO]VERIFY 

SHOW OUTPUT 


Executes a command procedure 

(Establishes, displays) the default file 
specification that the debugger uses to search 
for command procedures 

Defines parameters to be passed to command 
procedures 

(Specifies, identifies) the debugger log file 

Controls whether a debugging session is 
logged 

Controls whether, in screen mode, the screen 
contents are logged as the screen is updated 

Controls whether debugger commands are 
displayed as a command procedure is executed 

Identifies the current output options 
established by the SET OUTPUT command 
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2.4.12 Using Control Structures 

The following commands are used to establish conditional and looping structures 
for debugger commands: 

Executes a list of commands while 
incrementing a variable 

Executes a list of commands conditionally 

Executes a list of commands a specified 
number of times 

Executes a list of commands while a condition 
is true 

Exits an enclosing WHILE, REPEAT, or FOR 
loop 


FOR 

IF 

REPEAT 

WHILE 

EXITLOOP 


2.4.13 Debugging Multiprocess Programs 

The following commands are used for debugging multiprocess programs: 


CONNECT 

DEFINE/PROCESS.GROUP 

DO 

SET MODE [NOIINTEERUPT 

(SET,SHOW) PROCESS 


Brings a process under debugger control 

Assigns a symbolic name to a list of process 
specifications 

Executes commands in the context of one or 
more processes 

Controls whether execution is interrupted in 
other processes when it is suspended in some 
process 

Modifies the multiprocess debugging 
environment, displays process information 


2.4.14 Additional Commands 

The following commands are used 

(DISABLE,ENABLE.SHOW) AST 

(SET,SHOW) EVENT_FACILITY 

(SET,SHOW) LANGUAGE 
SET MODE [NOISEPARATE 

SET OUTPUT [NOJTERMINAL 

SET PROMPT 
(SET,SHOW) TASK 

(SET,SHOW) VECTORJMODE 
SHOW EXITJHANDLERS 


for miscellaneous purposes: 

(Disables, enables) the delivery of ASTs in 
the program, identifies whether delivery is 
enabled or disabled 

(Establishes, identifies) the current run-time 
facility for language-specific events 

(Establishes, identifies) the current language 

Controls whether the debugger, when used 
on a workstation running VWS, creates a 
separate window for debugger input and 
output 

Controls whether debugger output, except 
for diagnostic messages, is displayed or 
suppressed 

Specifies the debugger prompt 

Modifies the tasking environment, displays 
task information 

Enables or disables a debugger vector mode 
option, identifies the current vector mode 
option (for vectorized programs). 

Identifies the exit handlers declared in the 
program 


2-29 






Introduction to the Debugger: Command Interface 
2.4 Debugger Command Summary 


SHOW MODE 

SHOW OUTPUT 
SYNCHRONIZE VECTOR. 


Identifies the current debugger modes 
established by the SET MODE command 
(for example, screen mode, step mode) 

Identifies the current output options 
established by the SET OUTPUT command 

MODE Forces immediate synchronization between 

the scalar and vector processors (for vectorized 
programs) 


2-30 











_3 

Controlling and Monitoring Program Execution 


This chapter describes the options for invoking the debugger and for controlling 
and monitoring program execution while debugging. 

The chapter includes information that is common to all programs. 

• See Chapter 10 for additional information specific to multiprocess programs. 

• See Chapter 11 for additional information specific to vectorized programs. 

3.1 Starting and Ending a Debugging Session 

This section explains how to do the following: 

• Compile and link your program so you can invoke the debugger 

• Start, interrupt, resume, and end a debugging session 

3.1.1 Invoking the Debugger with the DCL RUN Command 

The usual way to invoke the debugger is as follows: 

1. Compile your program using the /DEBUG and /NOOPTIMIZE (or equivalent) 
qualifiers with the DCL compiler command (consult your language 
documentation to determine the compiler command defaults). 

2. Link your program using the /DEBUG qualifier with the DCL command 
LINK. 

3. Use the DCL command SHOW LOGICAL DBG$PROCESS to make sure that 
the value of the logical name DBG$PROCESS is appropriate for the type of 
program you are debugging (see Section 10.2.1): 

• If you are debugging a program that runs in only one process, 
DBG$PROCESS should be either undefined or should have the value 
DEFAULT. 

• If you are debugging a program that runs in more than one process, 
DBG$PROCESS should have the value MULTIPROCESS. 

4. Execute your program using the DCL RUN command. The debugger initially 
takes control of the program and prompts for commands. 

Note that you cannot run a program under debugger control over a DECnet link. 
Both the image to be debugged and the debugger must reside on the same node. 

The following example illustrates the previous steps with a simple Pascal 
program, INVENTORY, that consists of two compilation units whose source code 
is in two separate files, FORMS.PAS and INVENTORY.PAS. INVENTORY is the 
main program unit. 
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$ PASCAL/DEBUG/NOOPTIMIZE FORMS, INVENTORY 
$ LINK/DEBUG INVENTORY, FORMS 
$ RUN INVENTORY 

VAX DEBUG Version 5.5 

IDEBUG-I-INITIAL, language is PASCAL, module set to INVENTORY 
DBG> 

When the debugger first takes control, it does the following: 

• Displays its banner. 

• Sets the language-dependent parameters to the language of the main program 
(the module that contains the image transfer address). The "INITIAL" 
message identifies the language to which the debugging session is initialized 
and the name of the main program (Pascal and INVENTORY, respectively, 
in the previous example). See Section 4.1.8 and Section 4.1.9 for more 
information about language-dependent parameters. 

• Executes any user-defined initialization file (see Section 8.2). 

• Suspends execution at the beginning of the main program. The DBG> 
prompt, which is displayed whenever the debugger suspends execution, 
indicates that you can now enter debugger commands. 

In some cases the debugger suspends execution before the beginning of the main 
program and displays the following additional message: 

IDEBUG-I-NOTATMAIN, type GO to get to start of main program 

See Section 9.3 for an explanation of this message. 

The effect of the qualifiers used with the compiler command (PASCAL, in this 
example) and the LINK command is as follows. 

The /DEBUG qualifier on the compiler command loads the debugger symbol 
information associated with each compilation unit into its object module. This 
symbol information enables you to use, in debugger commands, the names of 
variables, routines, labels, and other symbols as they appear in the source code. 
By specifying options with the /DEBUG qualifier, you can control the level of 
symbolic information provided (see Section 5.1.1). This qualifier does not affect 
whether the debugger is invoked or how it is invoked. 

Most compilers optimize code to reduce the size of the program and make it 
run faster. For example, invariant expressions are removed from DO loops so 
that they are evaluated only once at run time; also, some memory locations 
might be allocated to different variables at different points in the program. The 
/NOOPTIMIZE (or equivalent) qualifier ensures that the code is not optimized 
and, therefore, that the contents of all program locations are consistent with what 
you would expect from looking at the source code. Section 9.1 describes some of 
the effects of optimization. 

Note also another possible cause of unexpected behavior. The debugger and your 
program share the same address space. In some rare cases, this can cause the 
debugger to affect how your program executes. Section 3.7 explains how the 
debugger controls execution and the possible sources of interference. 

The /DEBUG qualifier on the LINK command provides the following functions: 

• Copies the debugger symbol information from the object modules being linked 
into the debug symbol table (DST) and puts the DST in the executable image. 
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• Directs the image activator to pass control to the debugger when you 
subsequently execute the image with the RUN command. 

See Section 5.1.3 for more details on how the LINK command controls symbol 
information. 

Even if you have compiled and linked an image with the /DEBUG command 
qualifier, you can execute that image normally, without it being under debugger 
control. To do so, use the /NODEBUG qualifier on the DCL RUN command. For 
example: 

$ RUN/NODEBUG INVENTORY 

This is convenient for checking your program after you think it is error free. 

But the data required by the debugger still occupies space within the executable 
image. So, when you think your program is correct, you might want to link your 
program again without the /DEBUG qualifier. This creates an image with only 
traceback data in the DST, to use less disk space. 

Table 3-1 summarizes how to control debugger activation by means of LINK and 
RUN command qualifiers. Note that the LINK command qualifiers /[NOJDEBUG 
and /[NOJTRACEBACK affect not only debugger activation but also the level of 
symbol information provided. 


Table 3-1 Controlling Debugger Activation with the LINK and RUN Commands 


LINK Command To Run Program With To Run Program Without Maximum Symbol 

Qualifier Debugger Debugger Information Available 1 


/DEBUG 

RUN 

RUN/NODEBUG 

Full 

/TRACEBACK or 
/NODEBUG 2 

RUN/DEBUG 

RUN 

Only traceback 3 

/NOTRACEBACK 

Cannot 

RUN 

None 


1 The level of symbol information available while debugging is controlled both by the compile command qualifier and the 
LINK command qualifier (see Section 5.1). 


2 LINK/TRACEBACK (or LINK/NODEBUG) is a LINK command default. 

3 Traceback information includes compiler-generated line numbers and the names of routines and modules (compilation 
units). This symbol information is used by the VMS traceback condition handler to identify the PC value and the active 
calls when a run-time error has occurred. The information is also used by the debugger SHOW CALLS command (see 
Section 2.2.8.3X 


3.1.2 Invoking the Debugger with the DCL DEBUG Command 

You can invoke the debugger while your program is executing freely—for example, 

if you suspect that the program might be in an infinite loop or if you see erroneous 

output. 

To invoke the debugger in this manner, proceed as follows: 

1. Compile and link the program with the /DEBUG command qualifier, as 
described in the previous section (you can also use LINK/TRACEBACK, but 
only traceback symbols are then available while you debug). 

2. Enter the DCL command RUN/NODEBUG to execute the program without 
debugger control. 

3. Press Ctrl/Y to interrupt the executing program. Control then passes to the 
DCL command interpreter. 
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4. Enter the DCL command DEBUG to activate the debugger. It displays 
its banner, sets the language-dependent parameters to the language of 
the module where execution was interrupted, executes any user-defined 
initialization file, and prompts for commands. Usually you will not know 
where execution was interrupted. Enter the SHOW CALLS command to 
identify the current PC value and the sequence of routine calls on the call 
stack (the SHOW CALLS command is described in Section 2.2.8.3X 

For example: 

$ PASCAL/DEBUG/NOOPTIMIZE FORMS,INVENTORY 
$ LINK/DEBUG INVENTORY,FORMS 
$ RON/NODEBUG INVENTORY 


[cwy| 

Interrupt 
$ DEBUG 

VAX DEBUG Version 5.5 

IDEBUG-I-INITIAL, language is PASCAL, module set to INVENTORY 
DBG> SHOW CALLS 


Interrupting a running program with Ctrl/Y and then invoking the debugger with 
the DEBUG command is useful under the following conditions: 

• Your program is in an infinite loop. 

• After entering the RUN/NODEBUG command, you decide that you want 
debugger control. 

• You have not specified the /DEBUG command qualifier at compile time, link 
time, or run time but want to debug your running program. In this case, 
traceback information is the only symbol information available for debugging. 

3.1.3 Ending a Debugging Session 

To end a debugging session in an orderly manner, use the EXIT or QUIT 
commands, or press Ctrl/Z. These commands invoke the debugger exit handlers to 
close log files, restore the screen and keypad states, and so on. 

The EXIT command and Ctrl/Z have the same effect. The QUIT command is like 
the EXIT command or Ctrl/Z, except that the EXIT command and Ctrl/Z also 
execute any exit handlers that are declared in your program; the QUIT command 
does not. 

3.2 Interrupting and Resuming a Debugging Session 

As explained in Section 2.2.5, use Ctrl/C (not Ctrl/Y) to abort the execution 
of a debugger command or to interrupt program execution. This is useful if a 
command takes a long time to complete or your program is in an infinite loop. 
Control is returned to the debugger rather than to the DCL command interpreter. 

The debugger SPAWN and ATTACH commands enable you to interrupt a 
debugging session from the debugger prompt, enter DCL commands, and return 
to the debugger prompt. These commands function essentially like the DCL 
commands SPAWN and ATTACH. 
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Use the debugger command SPAWN to create a subprocess. Use the debugger 
command ATTACH to attach to an existing process or subprocess. 

You can enter the SPAWN command with or without specifying a DCL command 
as parameter. If you specify a DCL command, it is executed in a subprocess 
(if the DCL command invokes a utility, that utility is invoked in a subprocess). 
Control returns to the debugging session when the DCL command terminates 
(or when you exit the utility). The following example shows spawning the DCL 
command DIRECTORY. 

DBG> SPAWN DIR [JONES.PROJECT2]*.FOR 


IDEBUG-I-RETURNED, control returned to process J0NES_1 
DBG> 

The next example illustrates spawning the DCL command MAIL, which invokes 
the MAIL utility: 

DBG> SPAWN MAIL 
MAIL> READ/NEW 


MAIL> EXIT 

%DEBUG-I-RETURNED, control returned to process J0NES_1 
DBG> 

If you enter the SPAWN command without specifying a parameter, a subprocess 
is created, and you can then enter DCL commands. Either logging out of the 
subprocess or attaching to the parent process (with the DCL ATTACH command) 
returns you to the debugging session. For example: 

DBG> SPAWN 
$ RUN PR0G2 


$ ATTACH J0NES_1 

%DEBUG-I-RETURNED, control returned to process J0NES_1 
DBG> 

If you plan to go back and forth several times between your debugging session 
and a spawned subprocess (which might be another debugging session), use the 
debugger ATTACH command to attach to that subprocess. Use the DCL ATTACH 
command to return to the parent process. Because you do not create a new 
subprocess every time you leave the debugger, you use system resources more 
efficiently. 

If you are running two debugging sessions simultaneously, you can define a new 
debugger prompt for one of the sessions with the SET PROMPT command. This 
helps you to differentiate the sessions. 

3.3 Commands Used to Execute the Program 

Only four debugger commands can be used to execute your program: 

GO 

STEP 

CALL 

EXIT (if your program has exit handlers) 
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As indicated in Section 2.2.8.1, GO and STEP are the basic commands for starting 
and resuming program execution. The STEP command is discussed further in 
Section 3.4. 

During a debugging session, routines are executed as they are called during the 
execution of a program. The CALL command enables you to arbitrarily call and 
execute a routine that was linked with your program. This command is discussed 
in Section 8.7. 

The EXIT command was discussed in Section 3.1.3, in conjunction with ending a 
debugging session. Because it executes any exit handlers in your program, it is 
also useful for debugging exit handlers (see Section 9.5). 

When using any of these four commands, keep in mind that program execution 
can be interrupted or stopped by any of the following events: 

• The program terminates. 

• A breakpoint is reached. 

• A watchpoint is activated. 

• An exception is signaled. 

• You press Ctrl/C. 

3.4 Executing the Program by Step Unit 

The STEP command (probably the most frequently used debugger command) 
enables you to execute your program in small increments called step units. 

By default, a step unit is an executable line of source code. In the following 
example, the STEP command executes one line, reports the action ("stepped 
to . . . "), and displays the line number (27) and source code of the next line to be 
executed: 

DBG> STEP 

stepped to TEST\COUNT\%LINE 27 
27: X := X + 1; 

DBG> 

Execution is now suspended at the first machine code instruction for line 27 of 
module TEST. Line 27 is in COUNT, a routine within module TEST. 

The STEP command can also execute several source lines at a time. If you specify 
a positive integer as a parameter, the STEP command executes that number of 
lines. In the following example, the STEP command executes the next three lines: 

DBG> STEP 3 

stepped to TEST\COUNT\%LINE 34 
34: SWAP(X,Y); 

DBG> 

Note that only those source lines for which code instructions were generated by 
the compiler are recognized as executable lines by the debugger. The debugger 
skips over any other lines—for example, comment lines. Also, if a line has more 
than one statement on it, the debugger executes all the statements on that line 
as part of the single step. 

Source lines are displayed by default after stepping if they are available for the 
module being debugged. Source lines are not available if you are stepping in code 
that has not been compiled or linked with the /DEBUG qualifier (for example, 
a shareable image routine). If source lines are available, you can control their 
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display with the SET STEP [NOJSOURCE command and the /[NO]SOURCE 
qualifier of the STEP command. See Chapter 6 for information about how to 
control the display of source code in general and in particular after stepping. 

3.4.1 Changing the STEP Command Behavior 

The default behavior of the STEP command can be altered in the following two 
ways: 

• By specifying a STEP command qualifier—for example, STEP 
/INSTRUCTION. 

• By establishing a new default qualifier with the SET STEP command—for 
example, SET STEP INSTRUCTION. 

In the following example, the STEP/INSTRUCTION command executes the 
next instruction rather than the next line (STEP/LINE is the default behavior). 
The debugger displays the source line (10) associated with the new PC value 
(instruction TSTL): 

DBG> STEP/INSTRUCTION 

stepped to SQUARES$MAIN\%LINE 10+4: TSTL W A -164(Rll)[RO] 

10: IF(INARR(I) .NE. 0) THEN 

DBG> 

After the STEP/INSTRUCTION command executes, subsequent STEP commands 
revert to the default behavior. 

In contrast, the SET STEP command enables you to establish new defaults for 
the STEP command. These defaults remain in effect until another SET STEP 
command is entered. For example, the SET STEP INSTRUCTION command 
causes subsequent STEP commands to behave like STEP/INSTRUCTION (SET 
STEP LINE causes subsequent STEP commands to behave like STEP/LINE). 

There is a SET STEP command parameter for each STEP command qualifier. 

You can override the current STEP command defaults for the duration of a single 
STEP command by specifying other qualifiers. Use the SHOW STEP command to 
identify the current STEP command defaults. 

3.4.2 Stepping Into and Over Routines 

By default, when the PC is at a call statement and you enter the STEP command, 
the debugger steps "over" the called routine. Although the routine is executed, 
execution is not suspended within the routine but, rather, on the beginning of 
the line that follows the call statement. When stepping by instruction, execution 
is suspended on the instruction that follows a called routine’s RET (return from 
routine) instruction. 

To step into a called routine when the PC is at a call statement, enter the STEP 
/INTO command. The following example shows how to step into the routine 
PRODUCT, which is called from routine COUNT of module TEST: 

DBG> STEP 

stepped to TEST\COUNT\%LINE 18 

18: AREA := PRODUCT(LENGTH, WIDTH); 

DBG> STEP/INTO 

stepped to routine TEST\PRODUCT 

6: function PRODUCT(X,Y : INTEGER) return INTEGER is 

DBG> 
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To return to the calling routine from any point within the called routine, use the 
STEP/RETURN command. It causes the debugger to step to the RET instruction 
of the routine being executed. A subsequent STEP command brings you back to 
the statement that follows the routine call. For example: 

DBG> STEP/RETURN 

stepped on return from TEST\PRODUCT\%LINE 11 to TEST\PRODUCT\%LINE 15+4 
15: end PRODUCT; 

DBG> STEP 

stepped to TEST\COUNT\%LINE 19 

19: LENGTH := LENGTH + 1; 

DBG> 

To step into several routines, enter the SET STEP INTO command to change the 
default behavior of the STEP command from STEP/OVER to STEP/INTO: 

DBG> SET STEP INTO 

As a result of this command, when the PC is at a call statement, a STEP 
command suspends execution within the called routine. If you later want to step 
over routine calls, enter the SET STEP OVER command. 

When SET STEP INTO is in effect, you can qualify the kinds of called routines 
that the debugger is stepping into by specifying any of the following parameters 
with the SET STEP command: 

• [NO]JSB—Controls whether to step into routines called by JSB instructions. 

• [NO]SHARE—Controls whether to step into called routines in shareable 
images. 

• [NOJSYSTEM—Controls whether to step into called system routines. 

These parameters make it possible to step into application-defined routines and 
automatically step over system routines, and so on. For example, the following 
command directs the debugger to step into called routines in user space only. The 
debugger steps over routines in system space and in shareable images. 

DBG> SET STEP INTO,NOSYSTEM,NOSHARE 

3.5 Suspending and Tracing Execution with Breakpoints and 
Tracepoints 

This section discusses use of the SET BREAK and SET TRACE commands to, 
respectively, suspend and trace program execution. The commands are discussed 
together because of their similarities. 

SET BREAK Command Overview 

The SET BREAK command enables you to specify program locations or events at 
which to suspend program execution (breakpoints). After setting a breakpoint, 
you can start or resume program execution with the GO command, letting 
the program run until the specified location or condition is reached. When 
the breakpoint is triggered, the debugger suspends execution, identifies the 
breakpoint, and displays the DBG> prompt. You can then enter debugger 
commands—for example, to determine where you are (with the SHOW CALLS 
command), step into a routine, examine or modify variables, and so on. 

The syntax of the SET BREAK command is as follows: 

SET BREAK[/qua//7/'e/{... ]] [address-expressior{, ... ]] 

[WHEN ( conditional-expression )] 

[DO (command^; ...])] 
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The following example shows a typical use of the SET BREAK command and 
illustrates the general default behavior of the debugger at a breakpoint. 

In this example, the SET BREAK command sets a breakpoint on routine COUNT 
(at the beginning of the routine’s code). The GO command starts execution. When 
routine COUNT is encountered, execution is suspended, the debugger announces 
that the breakpoint at COUNT has been reached ("break at ... "), displays the 
source line (54) where execution is suspended, and prompts for another command: 

DBG> SET BREAK COUNT 
DBG> GO 


break at routine PR0G2\C0UNT 

54: procedure COUNT(X,Y:INTEGER); 

DBG> 

SET TRACE Command Overview 

The SET TRACE command enables you to select program locations or events for 
tracing the execution of your program without stopping its execution (tracepoints). 
After setting a tracepoint, you can start execution with the GO command and 
then monitor that location, checking for unexpected behavior. By setting a 
tracepoint on a routine, you can also monitor the number of times it is called. 

The debugger’s default behavior at a tracepoint is identical to that at a 
breakpoint, except that program execution continues past a tracepoint. Thus, 
the DBG> prompt is not displayed when a tracepoint is reached and announced 
by the debugger. 

Except for the command name, the syntax of the SET TRACE command is 
identical to that of the SET BREAK command: 

SET TRACE[/qualified ... ]] [address-expressior{, ... ]] 

[WHEN ( conditional-expression )] 

[DO ( command [; ...])] 

The SET TRACE and SET BREAK commands have the same qualifiers. When 
using the SET TRACE command, you specify address expressions, qualifiers, and 
the optional WHEN and DO clauses exactly as with the SET BREAK command. 

Unless you use the /TEMPORARY qualifier on the SET BREAK (or SET TRACE) 
command, breakpoints (and tracepoints) remain in effect until you cancel them or 
exit the debugging session. 

To identify all of the breakpoints (or tracepoints) that are currently set, use 
the SHOW BREAK (or SHOW TRACE) command. To cancel breakpoints (or 
tracepoints), use the CANCEL BREAK (or CANCEL TRACE) command (see 
Section 3.5.6). 

The following sections describe how to specify program locations and events with 
the SET BREAK and SET TRACE commands. 
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3.5.1 Setting Breakpoints or Tracepoints on Individual Program Locations 

To set a breakpoint (or a tracepoint) on a particular program location, specify an 
address expression with the SET BREAK (or SET TRACE) command. 

Fundamentally, an address expression specifies a memory address or a VAX 
register. Because the debugger understands the symbols associated with your 
program, the address expressions you typically use with the SET BREAK (or SET 
TRACE) command are routine names, labels, or source line numbers rather than 
memory addresses—the debugger converts these symbols to addresses. 

3.5.1.1 Specifying Symbolic Addresses 

_ Note_ 

In some cases, when using the SET BREAK or SET TRACE command 
with a symbolic address expression, you might need to set a module or 
specify a scope or a path name. Those concepts are described in detail in 
Chapter 5. The examples in this section assume that all modules are set 
and that all symbols referenced are uniquely defined, unless otherwise 
indicated. 


The following examples illustrate how to set a breakpoint (or a tracepoint) on a 
routine (SWAP) and a label (LOOP1): 

DBG> SET BREAK SWAP 
DBG> SET TRACE L00P1 

The next command sets a breakpoint on the RET (return) instruction of routine 
SWAP. "Breaking" on the RET instruction of a routine enables you to inspect the 
local environment before the RET instruction removes the routine’s call frame 
from the call stack. 

DBG> SET BREAK/RETURN SWAP 

Some languages, for example FORTRAN, use numeric labels. To set a breakpoint 
(or a tracepoint) on a numeric label, you must precede the number with the built- 
in symbol %LABEL. Otherwise, the debugger interprets the number as a memory 
address. For example, the following command sets a tracepoint on label 20. 

DBG> SET TRACE %LABEL 20 

You can set a breakpoint (or a tracepoint) on a line of source code by specifying 
the line number preceded by the built-in symbol %LINE. The following command 
sets a breakpoint on line 14. 

DBG> SET BREAK %LINE 14 

The preceding breakpoint causes execution to be suspended when the PC value 
is on the first instruction of line 14. Note that you can set a breakpoint (or a 
tracepoint) only on lines for which the compiler-generated instructions (lines that 
resulted in executable code). If you specify a line number that is not associated 
with an instruction, such as a comment line or a statement that declares but does 
not initialize a variable, the debugger issues a diagnostic message. For example: 

DBG> SET BREAK %LINE 6 

%DEBUG-I-LINEINFO, no line 6, previous line is 5, next line is 8 
%DEBUG-E-NOSYMBOL, symbol '%LINE 6' is not in the symbol table 
DBG> 

The preceding messages indicate that the compiler did not generate instructions 
for lines 6 or 7 in this case. 
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Some languages, for example BASIC, allow more than one statement on a line. 

In such cases, you can use statement numbers to differentiate among statements 
on the same line. A statement number consists of a line number, followed by a 
period (.) and a number indicating the statement. The format is as follows: 

%LINE line-number.statement-number 

For example, the following command sets a tracepoint on the second statement of 
line 38: 

DBG> SET TRACE %LINE 38.2 

When searching for symbols that you reference in commands, the debugger 
uses the conventions described in Section 5.3.1. That is, it first looks within the 
module where execution is currently suspended, then in other scopes associated 
with routines on the call stack, and so on. Therefore, to specify a symbol that is 
defined in more than one module, such as a line number, you might need to use 
a path name. For example, the following command sets a tracepoint on line 27 of 
module MOD4: 

DBG> SET TRACE M0D4\%LINE 27 

Remember the symbol lookup conventions when specifying a line number in 
debugger commands. If that line number is not defined in the module where 
execution is suspended (because it is not associated with an instruction), the 
debugger uses the symbol lookup conventions to locate another module where the 
line number is defined. 

When specifying address expressions, you can combine symbolic addresses with 
byte offsets. Thus, you can set a breakpoint (or a tracepoint) on a particular 
assembly language instruction by specifying its line number and the byte offset 
from the beginning of that line to the first byte of the instruction. For example, 
the next command sets a breakpoint on the address that is five bytes beyond the 
beginning of line 23. 

DBG> SET BREAK %LINE 23+5 

3.5.1.2 Specifying Locations in Memory 

To set a breakpoint (or a tracepoint) on a location in memory, specify its numerical 
address in the currently set radix. The default radix for both data entry and 
display is decimal for all languages except BLISS and MACRO. It is hexadecimal 
for BLISS and MACRO. For example, the following command sets a breakpoint at 
address 2753, decimal (for all languages except BLISS or MACRO), or at address 
2753, hexadecimal (for BLISS and MACRO): 

DBG> SET BREAK 2753 

You can specify a radix when you enter an individual integer literal (such as 
2753) by using one of the built-in symbols %BIN, %OCT, %DEC, or %HEX. For 
example, in the following command line the symbol %HEX specifies that 2753 
should be treated as a hexadecimal integer: 

DBG> SET BREAK %HEX 2753 

Note that when specifying a hexadecimal number that starts with a letter rather 
than a number, you must add a leading "0". Otherwise, the debugger tries to 
interpret the entity specified as a symbol declared in your program. 

See Section 4.1.9 and Appendix D for additional information about specifying 
radixes and on the built-in symbols %BIN, %DEC, %HEX, and %OCT. 
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If a breakpoint (or a tracepoint) was set on a numerical address that corresponds 
to a symbol in your program, the SHOW BREAK (or SHOW TRACE) command 
identifies the breakpoint symbolically. 

3.5.1.3 Obtaining and Symbolizing Memory Addresses 

Use the EVALUATE/ADDRESS command to determine the memory address 
associated with a symbolic address expression, such as a line number, routine 
name, or label. For example: 

DBG> EVALUATE/ADDRESS SWAP 
1536 

DBG> EVALUATE/ADDRESS %LINE 26 

1629 

DBG> 

The address is displayed in the current radix. You can specify a radix qualifier to 
display the address in another radix. For example: 

DBG> EVALUATE/ADDRESS/HEX %LINE 26 

0000065D 

DBG> 

The SYMBOLIZE command does the reverse of EVALUATE/ADDRESS. It 
converts a memory address into its symbolic representation (including its path 
name) if such a representation is possible. Chapter 5 explains how to control 
symbolization. See Section 4.1.10 for more information about obtaining and 
symbolizing addresses. 

3.5.2 Setting Breakpoints or Tracepoints on Lines or Instructions 

Several SET BREAK (and SET TRACE) command qualifiers cause the debugger 
to break on (or trace) every source line or every assembly language instruction of 
a particular class: 

/LINE 

/BRANCH 

/CALL 

/INSTRUCTION 
/INSTRUCTION=(opcode[, ... ]) 

When using these qualifiers, do not specify an address expression. 

For example, the following command causes the debugger to break on the 
beginning of every source line encountered during execution: 

DBG> SET BREAK/LINE 

The instruction-related qualifiers are especially useful for opcode tracing, which 
is the tracing of all instructions or the tracing of a class of instructions. The next 
command causes the debugger to trace every branch instruction encountered (for 
example BEQL, BGTR, and so on): 

DBG> SET TRACE/BRANCH 

Note that opcode tracing slows program execution. 

By default, when you use the qualifiers discussed in this section, the debugger 
breaks (or traces) within all called routines as well as within the currently 
executing routine (this is equivalent to specifying SET BREAK/INTO or SET 
TRACE/INTO). By specifying SET BREAK/OVER or SET TRACE/OVER, you can 
suppress break (or trace) action within all called routines. Or, you can use the 
/[NO]JSB, /[NO]SHARE, or /[NO]SYSTEM qualifiers to specify the kinds of called 
routines where break (or trace) action is to be suppressed. For example, the 
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next command causes the debugger to break on every line except within called 
routines that are in shareable images or system space: 

dbg> set break/line/noshare/nosystem 

3.5.3 Controlling Debugger Action at Breakpoints or Tracepoints 

The SET BREAK and SET TRACE commands provide several options for 
controlling the behavior of the debugger at breakpoints and tracepoints—the 
/AFTER, /[NOJSILENT, /[NO]SOURCE, and /TEMPORARY command qualifiers, 
and the optional WHEN and DO clauses. The following examples illustrate 
several of these options. 

The next command sets a breakpoint on line 14 and specifies that the breakpoint 
take effect after the fifth time that line 14 is executed: 

DBG> SET BREAK/AFTER:5 ILINE 14 

The next command sets a tracepoint that is triggered at every line of execution. 
The DO clause obtains the value of the variable X when each line is executed: 

DBG> SET TRACE/LINE DO (EXAMINE X) 

The next example illustrates how the WHEN and DO clauses can be used 
together. The command sets a breakpoint at line 27. The breakpoint is triggered 
(execution is suspended) only when the value of SUM is greater than 100 (not 
each time line 27 is executed). The DO clause causes the value of TEST_RESULT 
to be examined whenever the breakpoint is triggered—that is, whenever the value 
of SUM is greater than 100. If the value of SUM is not greater than 100 when 
execution reaches line 27, the breakpoint is not triggered and the DO clause is 
not executed. 

DBG> set BREAK ILINE 27 WHEN (SUM > 100) DO (EXAMINE TEST_RESULT) 

See Section 4.1.5 and Section d.3.2.2 for information about evaluating language 
expressions, such as the expression "SUM > 100". 

The /SILENT qualifier suppresses the break or trace message and source code 
display. This is useful when, for example, you want to use the SET TRACE 
command only to execute a debugger command at the tracepoint. In the next 
example, the SET TRACE command is used to examine the value of the Boolean 
variable STATUS at the tracepoint. 

DBG> SET TRACE/SILENT ILINE 83 DO (EXAMINE STATUS) 

DBG> GO 


SCREEN IO\CLEAR\STATUS: OFF 


In the next example, the SET TRACE command is used to count the number of 
times line 12 is executed. The first DEFINE/VALUE command defines a symbol 
COUNT and initializes its value to zero. The DO clause of the SET TRACE 
command causes the value of COUNT to be incremented and evaluated whenever 
the tracepoint is triggered (whenever execution reaches line 12). 

DBG> DEFINE/VALUE COUNT=0 

DBG> SET TRACE/SILENT ILINE 12 DO (DEF/VAL C0UNT=C0UNT+1;EVAL COUNT) 
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Source lines are displayed by default at breakpoints, tracepoints, and watchpoints 
if they are available for the module being debugged. You can also control their 
display with the SET STEP [NOJSOURCE command and the /[NO]SOURCE 
qualifier of the SET BREAK, SET TRACE, and SET WATCH commands. See 
Chapter 6 for information about how to control the display of source code in 
general and in particular at breakpoints, tracepoints, and watchpoints. 

3.5.4 Setting Breakpoints or Tracepoints on Exceptions 

The SET BREAK/EXCEPTION and SET TRACE/EXCEPTION commands direct 
the debugger to treat any exception generated by your program as a breakpoint 
or tracepoint, respectively. The breakpoint (or tracepoint) occurs before any 
application-declared exception handler is invoked. See Section 9.4 for debugging 
techniques associated with exceptions and condition handlers. 

3.5.5 Setting Breakpoints or Tracepoints on Events 

The SET BREAK and SET TRACE commands each have an /EVENT=eoent-name 
qualifier. You can use this qualifier to set breakpoints or tracepoints that are 
triggered by various events (denoted by event-name keywords). Events and their 
keywords are currently defined for the following event facilities: 

• ADA event facility, which defines VAX Ada tasking events. ADA events are 
defined in Section 12.6.4. 

• THREADS event facility, which defines tasking (multithread) events for 
programs written in any language that use DECthreads services. THREADS 
events are defined in Section 12.6.4. 

• SCAN event facility, which defines SCAN pattern-matching events. SCAN 
events are defined in Section E.12.6.1. 

The appropriate facility and event-name keywords are defined at debugger 
startup. Use the SHOW EVENT_FACILITY command to identify the current 
event facility and the associated event-name keywords. The SET EVENT_ 
FACILITY command enables you to change the event facility and thereby change 
your debugging context. This is useful if you have a multilanguage program and 
want to debug a routine that is associated with an event facility but that facility 
is not currently set. 

The following examples briefly illustrate how to set event breakpoints with 
tasking programs and SCAN programs. When a breakpoint or tracepoint is 
triggered, the debugger identifies the event that caused it to be triggered and 
gives additional information. 

The following command causes the debugger to break whenever any task enters 
the SUSPENDED state. 

DBG> SET BREAK/EVENT=SUSPENDED 

The next command sets two tracepoints, which are associated with the Ada tasks 
CHECKIN and RESERVE, respectively. Each tracepoint is triggered whenever 
its associated task makes a transition to the RUN state. 

DBG> SET TRACE/EVENT=RUN CHECKIN,RESERVE 

The next command causes the debugger to break whenever a SCAN token is 
built, for any value. 

DBG> SET BREAK/EVENT=TOKEN 

See Section 9.3.2 for information about predefined Ada event breakpoints. 
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3.5.6 Canceling Breakpoints or Tracepoints 

Use the CANCEL BREAK and CANCEL TRACE commands to cancel breakpoints 
and tracepoints, respectively. To cancel a breakpoint (or a tracepoint), specify 
address expressions and qualifiers exactly as you specified them when setting the 
breakpoint (or tracepoint). 

Thus, to cancel breakpoints (or tracepoints) that were set at specific address 
expressions, specify those same address expressions. For example: 

DBG> CANCEL BREAK SWAP,MOD2\LOOP4,2753 

To cancel breakpoints (or tracepoints) that were set with the following command 
qualifiers, specify those same command qualifiers: 

/BRANCH 

/CALL 

/EVENT=event-name 
/EXCEPTION 
/INSTRUCTION 
/INSTRUCTION=(opcoc?e[, ... ]) 

/LINE 

If the qualifier requires one or more keywords, include the keywords associated 
with the breakpoints or tracepoints to be canceled. For example: 

DBG> CANCEL BREAK/LINE 

DBG> CANCEL TRACE/INSTRUCTION=(JSB,CALLS) 

DBG> CANCEL TRACE/EVENT=RUN CHECKIN 

3.6 Monitoring Changes in Variables and Other Program Locations 

The SET WATCH command enables you to specify program variables (or arbitrary 
memory locations) that the debugger monitors as your program executes. This 
process is called setting watchpoints. If, during execution, the program modifies 
the value of a "watched" variable (or memory location), the watchpoint is 
triggered. The debugger then suspends execution, displays information, and 
prompts for more commands. The debugger monitors watchpoints continuously 
during program execution. 

This section describes the general use of the SET WATCH command. Section 3.6.2 
gives additional information pertaining to setting watchpoints on nonstatic 
variables—variables that are allocated on the call stack or in registers. 

_ Note _ 

In some cases, when using the SET WATCH command with a variable 
name (or any other symbolic address expression), you might need to set a 
module or specify a scope or a path name. Those concepts are described 
in Chapter 5. The examples in this section assume that all modules are 
set and that all variable names are uniquely defined. 

If your program was optimized during compilation, certain variables in 
the program might be removed by the compiler. If you then try to set 
a watchpoint on such a variable, the debugger issues a warning (see 
Section 9.1). 
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The syntax of the SET WATCH command is as follows: 

SET \NKTCH[/qualified ... ]] [address-expression{, ... ]] 

[WHEN ( conditional-expression )] 

[DO (command ^-,...])] 

Although any valid address expression can be specified, usually you specify the 
name of a variable. The example that follows shows a typical use of the SET 
WATCH command and illustrates the general default behavior of the debugger at 
a watchpoint. 

DBG> SET WATCH COUNT 
DBG> GO 


watch of M0D2\C0UNT at M0D2ULINE 24 
24: COUNT := COUNT + 1; 

old value: 27 
new value: 28 
break at M0D2ULINE 25 
25: END; 

DBG> 

In this example, the SET WATCH command sets a watchpoint on the variable 
COUNT, and the GO command starts execution. When the program changes the 
value of COUNT, execution is suspended. The debugger then does the following: 

• Announces the event ("watch of MOD2\COUNT ... "), identifying the 
location of the instruction that changed the value of the watched variable 
(" ... at MOD2\%LINE 24") 

• Displays the associated source line (24) 

• Displays the old and new values of the variable (27 and 28) 

• Announces that execution has been suspended at the beginning of the next 
line ("break at MOD2\%LINE 25") and displays that source line 

• Prompts for another command 

When the address of the instruction that modified a watched variable is not at 
the beginning of a source line, the debugger denotes the instruction’s location by 
displaying the line number plus the byte offset from the beginning of the line. 
For example: 

DBG> SET WATCH K 
DBG> GO 


watch of TEST\K at TEST\%LINE 19+5 
19: DO 40 K = 1, J 

old value: 4 
new value: 5 

break at TEST\%LINE 19+9 
19: DO 40 K = 1, J 

DBG> 

In this example, the address of the instruction that modified variable K is 5 bytes 
beyond the beginning of line 19. Note that the breakpoint is on the instruction 
that follows the instruction that modified the variable (not on the beginning of 
the next source line as in the preceding example). 


3-16 



Controlling and Monitoring Program Execution 
3.6 Monitoring Changes in Variables and Other Program Locations 


You can set watchpoints on aggregates (that is, entire arrays or records). A 
watchpoint set on an array or record triggers if any element of the array or 
record changes. Thus, you do not need to set watchpoints on individual array 
elements or record components. Note, however, that you cannot set an aggregate 
watchpoint on a variant record. In the following example, the watchpoint is 
triggered because element 3 of array ARR was modified: 

DBG> SET WATCH ARR 
DBG> GO 


watch of SUBR\ARR at SUBR\%LINE 12 
12: ARR(3) := 28 

old value: 

( 1 ) : 7 

( 2 ) : 12 

(3) : 3 

(4) : 0 

new value: 


. ii 

(3) : 28 

(4) : 0 

break at SUBR\%LINE 13 
DBG> 

You can also set a watchpoint on a record component, on an individual array 
element, or on an array slice (a range of array elements). A watchpoint set on an 
array slice triggers if any element within that slice changes. When setting the 
watchpoint, use the syntax of the current language. For example, the following 
command sets a watchpoint on element 7 of array CHECK using Pascal syntax: 

DBG> SET WATCH CHECK[7] 

To identify all of the watchpoints that are currently set, use the SHOW WATCH 
command. To cancel watchpoints, use the CANCEL WATCH command. 

Note that the SET BREAK/MODIFY and SET WATCH commands have the same 
effect. 

3.6.1 Watchpoint Options 

The SET WATCH command provides the same options for controlling the behavior 
of the debugger at watchpoints that the SET BREAK and SET TRACE commands 
provide for breakpoints and tracepoints—namely the /AFTER, /[NO]SILENT, 
/[NO]SOURCE, and /TEMPORARY qualifiers, and the optional WHEN and DO 
clauses. See Section 3.5.3 for examples. 

3.6.2 Watching Nonstatic Variables 

Storage for a variable in your program is allocated either statically or 
nonstatically. A static variable is associated with the same memory address 
throughout execution of the program. A nonstatic variable is allocated on 
the call stack or in a register and has a value only when its defining routine is 
active, on the call stack. As explained in this section, the technique for setting 
a watchpoint, the watchpoint’s behavior, and the speed of program execution are 
different for the two kinds of variables. 
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To determine how a variable is allocated, use the EVALUATE/ADDRESS 
command. A static variable generally has its address in PO space (0 to 
3FFFFFFF, hexadecimal). A nonstatic variable generally has its address in 
PI space (40000000 to 7FFFFFFF, hexadecimal) or is in a register. In the 
following Pascal code example, X is declared as a static variable, whereas Y is a 
nonstatic variable (by default). The EVALUATE/ADDRESS command, entered 
while debugging, shows that X is allocated at memory location 512, whereas Y is 
allocated in register R0: 


VAR 

X: [STATIC] INTEGER; 
Y: INTEGER; 


DBG> EVALUATE/ADDRESS X 
512 

DBG> EVALUATE/ADDRESS Y 

%R0 

DBG> 

When using the SET WATCH command, note the following distinction. You can 
set a watchpoint on a static variable regardless of the PC value when you enter 
the command; but you can set a watchpoint on a nonstatic variable only when 
the PC value is within the routine where that variable is defined. Otherwise, the 
debugger issues a warning. For example: 

DBG> SET WATCH Y 

%DEBUG-W-SYMN0TACT, nonstatic variable 'MOD4\ROUT3\Y' 
is not active 

DBG> 

Section 3.6.2.2 describes how to set a watchpoint on a nonstatic variable. 

3.6.2.1 Execution Speed 

When a watchpoint is set, the speed of program execution depends on whether 
the variable is static or nonstatic. To watch a static variable, the debugger write- 
protects the page containing the variable. If your program attempts to write to 
that page (modify the value of that variable), an access violation occurs and the 
debugger handles the exception. The debugger temporarily unprotects the page 
to allow the instruction to complete and then determines whether the watched 
variable was modified. Except when writing to that page, the program executes 
at full speed. 

Because problems arise if the call stack or registers are write-protected, the 
debugger must use another technique to watch a nonstatic variable. It traces 
every instruction in the variable’s defining routine and checks the value of the 
variable after each instruction has been executed. Because this significantly slows 
down the execution of the program, the debugger issues the following message 
when you set a nonstatic watchpoint: 

DBG> SET WATCH Y 

%DEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every instruction 
DBG> 
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3.6.2.2 Setting a Watchpoint on a Nonstatic Variable 

To set a watchpoint on a nonstatic variable, make sure that the PC value is 
within the defining routine. A convenient technique is to set a tracepoint on that 
routine, also specifying a DO clause to set the watchpoint. Thus, whenever the 
routine is called, the tracepoint is triggered and the watchpoint is automatically 
set on the local variable. In the following example, the WPTTRACE message 
indicates that a watchpoint has been set on Y, a nonstatic variable that is local to 
routine ROUT3: 

DBG> SET TRACE/NOSOURCE R0UT3 DO (SET WATCH Y) 

DBG> GO 


trace at routine MOD4\ROUT3 

%DEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every instruction 


watch of MOD4\ROUT3\Y at MOD4\ROUT3\%LINE 16 
16: Y := 4 

old value: 3 

new value: 4 

break at MOD4\ROUT3\%LINE 17 
17: SWAP(X,Y); 

DBG> 

When execution returns to the caller of routine ROUT3, variable Y is no longer 
active. Therefore, the debugger automatically cancels the watchpoint and issues 
the following messages: 

%DEBUG-I-WATCHVAR, watched variable MOD4\ROUT3\Y has gone out of scope 
%DEBUG-I-WATCHCAN, watchpoint now cancelled 

3.6.2.3 Options for Watching Nonstatic Variables 

The SET WATCH command qualifiers /OVER, /INTO, and /[NOJSTATIC provide 
options for watching nonstatic variables. 

When you set a watchpoint on a nonstatic variable, you can direct the debugger 
to do one of two things at a routine call: 

• Step over the called routine—executing it at full speed—and resume 
instruction tracing after returning. This is the default (SET WATCH/OVER). 

• Trace instructions within the called routine, thereby monitoring the variable 
instruction-by-instruction within the routine (SET WATCH/INTO). 

Using the SET WATCH/OVER command results in better performance. But 
it also means that, if the called routine modifies the watched variable, the 
watchpoint is triggered only after execution returns from that routine. The 
SET WATCH/INTO command slows down program execution but enables you to 
monitor watchpoints more precisely within called routines. 

The debugger determines whether a variable is static or nonstatic by looking 
at its address (PO space, PI space, or register). When entering a SET WATCH 
command, you can override this decision with the /[NO]STATIC qualifier. For 
example, if you have allocated nonstack storage in PI space, use the SET WATCH 
/STATIC command to specify that a particular variable is static even though it 
is in PI space. Conversely, if you have allocated your own call stack in PO space, 
use the SET WATCH/NOSTATIC command to specify that a particular variable is 
nonstatic even though it is in PO space. 
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3.6.2.4 Setting Watchpoints in Installed Writable Shareable Images 

When setting a watchpoint in an installed writable shareable image, use the SET 
WATCH/NOSTATIC command (see Section 3.6.2.3). 

The reason you must set a nonstatic watchpoint is as follows. Variables declared 
in such shareable images are typically static variables. By default, the debugger 
watches a static variable by write-protecting the page containing that variable. 
However, the debugger cannot write-protect a page in an installed writable 
shareable image. Therefore, the debugger must use the slower method of 
detecting changes, as for nonstatic variables—that is, by checking the value at the 
watched location after each instruction has been executed (see Section 3.6.2.1). 

Note that if any other process modifies the watched location’s value, the debugger 
may report that your program modified the watched location. 

3.7 How the Debugger Controls Program Execution 

This section is for readers who are interested in how the debugger functions. 

The debugger controls and monitors execution by causing exceptions to occur at 
points of interest in your program. For example, it might put a breakpoint fault 
instruction (BPT) in your code, causing a breakpoint exception to occur when that 
instruction is executed. The debugger might also set the trace enable bit (T bit) 
in the processor status longword (PSL), thus causing a trace trap at the end of 
each instruction. 

When you run your program with the debugger, the debugger is the primary 
exception handler. Any exception resulting from the execution of your program, 
whether or not it is caused by the debugger, is first handled by the debugger. 

If the debugger did not cause the exception, it resignals the exception (see 
Section 9.4 for information and debugging techniques related to exceptions and 
condition handlers). If the debugger caused the exception, it takes appropriate 
action. For example, in the case of a tracepoint the debugger identifies the 
tracepoint and returns control to the program. In the case of a breakpoint, the 
debugger maintains control by identifying the breakpoint and then prompting for 
commands. 

The following paragraphs illustrate the functioning of the debugger with 
some typical commands—SET BREAK and STEP. See also Section 3.6.2 and 
Section 9.4 for implementation information about the SET WATCH and SET 
BREAK/EXCEPTION commands, respectively. 

When you set a breakpoint, specifying a particular address expression, the 
debugger removes the opcode at that address and replaces it with the BPT 
instruction. When execution reaches that address, the BPT instruction causes a 
breakpoint fault, which gives control to the debugger: 

1. The debugger announces the breakpoint and prompts for commands. When 
you resume execution, the debugger performs the following steps. 

2. The debugger replaces the original opcode and sets the T bit of the saved PSL 
on the call stack, so that a trace trap occurs when the current instruction is 
executed. 

3. The instruction is executed. 

4. When the trace trap occurs, the debugger replaces the BPT instruction at 
the original breakpoint address, so that the break fault occurs whenever 
execution again reaches that address. 
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When you enter a STEP/INSTRUCTION command, the debugger sets the T bit of 
the saved PSL, executes the next instruction, then, when the trace trap occurs, 
issues a message and prompts for commands. 

The STEP/LINE command is implemented similarly, except that the debugger 
keeps track of line boundaries by correlating the low and high PC values of each 
line with data stored in the symbol table. The debugger completes the step and 
prompts for commands when you leave the current line. 

When you set a breakpoint on a class of instructions and then start execution, the 
debugger traces (traps on) every instruction by setting the T bit of the saved PSL. 
If the next instruction is of the desired class, the debugger suspends execution on 
that instruction, announces the breakpoint, and prompts for commands. If the 
instruction is not of the desired class, the debugger continues to trace and execute 
instructions. 

When you enter a STEP/OVER command at a routine call, the debugger does the 
following: 

1. Steps into the routine, then sets a reserved bit in the saved PSL. 

2. Lets the program run. The routine is executed, but the RET instruction 
causes a reserved-operand exception when it tries to restore the modified 
PSL. 

3. Lets the RET instruction complete but sets the T bit to suspend execution 
after the RET instruction (in the calling routine) on the instruction that 
follows the original call. 

STEP/RETURN is also implemented by setting a reserved bit in the saved PSL. 

Because the debugger and your program share the same address space, in some 
rare cases they can interfere with each other, causing unexpected behavior. The 
following paragraphs highlight possible sources of interference. 

Effect of Debugger on Uninitialized Variables 

Because the debugger acts as an exception handler, it uses the call stack. This 
can cause uninitialized variables saved on the call stack to be modified by the 
debugger. 

If your program references an uninitialized variable that is in this state, the 
execution of the program can be affected. 

Effect of Debugger on Memory Usage 

Another source of possible interference between the debugger and your program 
is that they share memory. If your program is sensitive to changes in memory 
usage, the execution of the program can be affected. 
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Examining and Manipulating Program Data 


This chapter explains how to use the EXAMINE and DEPOSIT commands to 
display and modify the values of symbols declared in your program as well as the 
contents of arbitrary program locations. The chapter also explains how to use the 
EVALUATE and other commands that evaluate language expressions. 

The topics covered in this chapter are organized as follows: 

• General concepts related to using the EXAMINE, DEPOSIT, and EVALUATE 
commands. 

• Use of the commands with symbolic names—for example, the names of 
variables and routines declared in your program. Such symbolic address 
expressions are associated with compiler generated types. 

• Use of the commands with program locations (memory addresses or registers) 
that do not have symbolic names. Such address expressions are not 
associated with compiler generated types. 

• Specifying a type to override the type associated with an address expression. 

The examples in this chapter do not cover all language-dependent behavior. 
When debugging in any language, be sure to also consult the following 
documentation: 

• Appendix E, which summarizes debugger support for each language. 

• Section 9.3, which highlights some important differences between languages 
that you should be aware of when debugging multilanguage programs. 

• The documentation supplied with that language. 


4.1 General Concepts 

This section introduces the EXAMINE, DEPOSIT, and EVALUATE commands 
and discusses concepts that are common to those commands. 

4.1.1 Accessing Variables While Debugging 

Before you try to examine or deposit into a nonstatic (stack-local or register) 
variable, its defining routine must be active—that is, on the call stack. That is, 
program execution must be suspended somewhere within the defining routine. 
See Section 3.6.2 for more information about nonstatic variables. 

You can examine a static variable at any time during program execution, and you 
can examine a nonstatic variable as soon as execution reaches its defining routine. 
However, before you examine any variable, you should step or otherwise execute 
the program beyond the point where the variable is declared and initialized. The 
value contained in any uninitialized variable should be considered invalid. 
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Many compilers optimize code to make the program run faster. If the code that 
you are debugging has been optimized, some program locations might not match 
what you would expect from looking at the source code. In particular, some 
optimization techniques eliminate certain variables, so that you no longer have 
access to them while debugging. 

Section 9.1 explains the effect of several optimization techniques on the 
executable code. When first debugging a program, it is best to disable 
optimization, if possible, with the /NOOPTIMIZE (or equivalent) compiler 
command qualifier. 

Note that, in some cases, when using the EXAMINE or DEPOSIT command with 
a variable name (or any other symbolic address expression) you might need to 
set a module or specify a scope or a path name. Those concepts are described in 
Chapter 5. The examples in this chapter assume that all modules are set and 
that all variable names are uniquely defined. 

4.1.2 Using the EXAMINE Command 

For high-level language programs, the EXAMINE command is used mostly to 
display the current value of variables, and it has the following form: 

EXAMINE variable-name{, ... ] 

Thus, for example, the following command displays the current value of the 
integer variable X: 

DBG> EXAMINE X 
M0D3\X: 17 

DBG> 

When displaying the value, the debugger prefixes the variable name with its path 
name—in this case, the name of the module where variable X is declared (see 
Section 5.3.2). 

More generally, the EXAMINE command displays the current value of the entity 
denoted by an address expression, in the type associated with that location 
(for example, integer, real, array, record, and so on). The basic format of the 
EXAMINE command is as follows: 

EXAMINE address-expressior{, ... ] 

When you enter an EXAMINE command, the debugger evaluates the address 
expression to yield a program location (a memory address or a register). The 
debugger then displays the value stored at that location as follows: 

• If the location has a symbolic name, the debugger formats the value according 
to the compiler generated type associated with that symbol. 

• If the location does not have a symbolic name, the debugger formats the value 
in the type longword integer by default. 

See Section 4.1.4 for more information about the types associated with symbolic 
and nonsymbolic address expressions. 

By default, when displaying the value, the debugger identifies the address 
expression and its path name symbolically if symbol information is available. See 
Section 4.1.10 for additional information about symbolization of addresses. 
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4.1.3 Using the DEPOSIT Command 

For high-level languages, the DEPOSIT command is used mostly to assign a 
new value to a variable. The command is like an assignment statement in most 
programming languages, and it has the following form: 

DEPOSIT variable-name = value 

Thus, for example, the following DEPOSIT command assigns the value 23 to the 
integer variable X: 

DBG> EXAMINE X 
M0D3\X: 17 

DBG> DEPOSIT X = 23 
DBG> EXAMINE X 
M0D3\X: 23 

DBG> 

More generally, the DEPOSIT command evaluates a language expression and 
deposits the resulting value into a program location denoted by an address 
expression. The basic format of the DEPOSIT command is as follows: 

DEPOSIT address-expression = language-expression 

When you enter a DEPOSIT command, the debugger does the following: 

• It evaluates the address expression to yield a program location. 

• If the program location has a symbolic name, the debugger associates the 
location with the symbol’s compiler generated type. If the location does not 
have a symbolic name, the debugger associates the location with the type 
longword integer, by default (see Section 4.1.4). 

• It evaluates the language expression in the syntax of the current language 
and in the current radix to yield a value. This behavior is identical to that of 
the EVALUATE command (see Section 4.1.5). 

• It checks that the value and type of the language expression is consistent 
with the type of the address expression. If you try to deposit a value that 
is incompatible with the type of the address expression, the debugger issues 
a diagnostic message. If the value is compatible, the debugger deposits the 
value into the location denoted by the address expression. 

Note that the debugger might do type conversion during a deposit operation if 
the language rules allow it. For example, assume X is an integer variable. In the 
following example, the real value 2.0 is converted to the integer value 2, which is 
then assigned to X: 

DBG> DEPOSIT X = 2.0 
DBG> EXAMINE X 
MOD3\X: 2 

DBG> 

In general, the debugger tries to follow the assignment rules for the current 
language. 
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4.1.4 Address Expressions and Their Associated Types 

The symbols that are declared in your program (variable names, routine names, 
and so on) are symbolic address expressions. They denote memory addresses 
or registers. Symbolic address expressions (also called symbolic names in this 
chapter) have compiler generated types, and the debugger knows the type and 
location that are associated with symbolic names. Section 4.1.10 explains how to 
obtain memory addresses and register names from symbolic names and how to 
symbolize program locations. 

Symbolic names include the following categories: 

• Variables. The associated program locations contain the current values 
of variables. Techniques for examining and depositing into variables are 
described in Section 4.2. 

• Routines, labels, and line numbers. The associated program locations 
contain VAX assembly-language instructions. Techniques for examining and 
depositing VAX instructions are described in Section 4.3. 

Program locations that do not have a symbolic name are not associated with 
a compiler generated type. To enable you to examine and deposit into such 
locations, the debugger associates them with the default type longword integer. 
This means that, if you specify a location that does not have a symbolic name, 
the EXAMINE command displays the contents of 4 bytes starting at the address 
specified and formats the displayed information as an integer value. In the 
following example, the memory address 926 is not associated with a symbolic 
name (note that the address is not symbolized when the EXAMINE command is 
executed). Therefore, the EXAMINE command displays the value at that address 
as a longword integer: 

DBG> EXAMINE 926 
926: 749404624 

DBG> 

Similarly, by default you can deposit up to 4 bytes of integer data into a program 
location that does not have a symbolic name. And this data is formatted as a 
longword integer. For example: 

DBG> DEPOSIT 926 = 84 
DBG> EXAMINE 926 
926: 84 

DBG> 

Techniques for examining and depositing into locations that do not have a 
symbolic name are described in Section 4.5. 

The EXAMINE and DEPOSIT commands accept type qualifiers (/ASCII:n, 
/BYTE, and so on) that enable you to override the type associated with a 
program location. This is useful if you want the contents of the location to 
be interpreted and displayed in another type, or if you want to deposit some 
value of a particular type into a location that is associated with another type. 
Techniques for overriding a type are described in Section 4.5. 
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4.1.5 Evaluating Language Expressions 

A language expression consists of any combination of one or more symbols, 
literals, and operators that is evaluated to a single value in the syntax of the 
current language and in the current radix. (The current language and current 
radix are defined in Section 4.1.8 and Section 4.1.9, respectively.) Several 
debugger commands and constructs evaluate language expressions: 

• The EVALUATE and DEPOSIT commands, which are described in this 
section and in Section 4.1.3, respectively. 

• The IF, FOR, REPEAT, and WHILE commands (see Section 8.6). 

• WHEN clauses, which are used with the SET BREAK, SET TRACE, and SET 
WATCH commands (see Section 3.5.3). 

Although this discussion applies to all commands and constructs that evaluate 
language expressions, it focuses on the use of the EVALUATE command. 

The EVALUATE command evaluates one or more language expressions in the 
syntax of the current language and in the current radix and displays the resulting 
values. The command has the following form: 

EVALUATE language-expression[, ... ] 

One use of the EVALUATE command is as a calculator, to perform arithmetic 
calculations that might be unrelated to your program. For example: 

DBG> EVALUATE (8+12)*6/4 
30 

DBG> 

The debugger uses the rules of operator precedence of the current language when 
evaluating language expressions. 

You can also evaluate language expressions that include variables and other 
constructs. For example, the following EVALUATE command subtracts 3 from 
the current value of the integer variable X, multiplies the result by 4, and 
displays the resulting value: 

DBG> DEPOSIT X = 23 
DBG> EVALUATE (X - 3) * 4 
80 

DBG> 

However, you cannot evaluate a language expression that includes a function call. 
For example, if PRODUCT is a function that multiplies two integers, you cannot 
enter the EVALUATE PRODUCT(3,5) command. If your program assigns the 
returned value of a function to a variable, you can then examine the value of that 
variable. 

If an expression contains symbols with different compiler generated types, the 
debugger uses the type-conversion rules of the current language to evaluate 
the expression. If the types are incompatible, a diagnostic message is issued. 
Debugger support for operators and other constructs in language expressions is 
tabulated in Appendix E for each language. You can also obtain information by 
using the HELP LANGUAGE language-name command. 
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The built-in symbol %CURVAL denotes the current value —the value last 
displayed by an EVALUATE or EXAMINE command, or deposited by a DEPOSIT 
command. The backslash (\ ) also denotes the current value when used in that 
context. For example: 

DBG> EXAMINE X 
M0D3\X: 23 

DBG> EVALUATE ICURVAL 
23 

DBG> DEPOSIT Y = 47 
DBG> EVALUATE \ 

47 

DBG> 

4.1.5.1 Using Variables in Language Expressions 

You can use variables in language expressions in much the same way that you 
use them in the source code of your program. 

Thus, the debugger generally interprets a variable used in a language expression 
as the current value of that variable, not the address of the variable. For example 
(X is an integer variable): 


DBG> DEPOSIT X = 12 

! Assign the value 12 to X 


DBG> EXAMINE X 

M0D4\X: 12 

! Display the value of X 


DBG> EVALUATE X 

12 

! Evaluate and display the value 

of X 

DBG> EVALUATE X + 4 

16 

! Add the value of X to 4 


DBG> DEPOSIT X = X/2 

! Divide the value of X by 2 and 
! the resulting value to X 

assign 

DBG> EXAMINE X 

M0D4\X: 6 

DBG> 

! Display the new value of X 



Note that the use of a variable in a language expression as illustrated in the 
previous examples is generally limited to single-valued, noncomposite variables. 
Typically, you can specify a multivalued, composite variable (like an array 
or record) in a language expression only if the syntax indicates that you are 
referencing only a single value (a single element of the aggregate). For example, 
if ARR is the name of an array of integers, the following command is invalid: 

DBG> EVALUATE ARR 

%DEBUG-W-NOVALUE, reference does not have a value 
DBG> 

However, the following commands are valid because only a single element of the 
array is referenced: 

DBG> EVALUATE ARR(2) ! Evaluate element 2 of array ARR 

37 

DBG> DEPOSIT K = 5 + ARR(2) ! Deposit the sum of two integer 

DBG> ! values into an integer variable 

Note also that, if the current language is BLISS, the debugger interprets a 
variable in a language expression as the address of that variable. To denote the 
value stored in a variable, you must use the contents-of operator (period (.)). For 
example, when the language is set to BLISS: 
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DBG> EXAMINE Y 
M0D4\Y: 3 

DBG> EVALUATE Y 
02475B 

DBG> EVALUATE .Y 
3 

DBG> EVALUATE Y + 4 
02475F 

DBG> EVALUATE .Y + 4 
7 

DBG> 


! Add 4 to the address of Y and 
! display the resulting value. 

! Add 4 to the value of Y and display 
! the resulting value. 


! Display the value of Y. 

! Display the address of Y. 


! Display the value of Y. 


For all languages, to obtain the address of a variable, use the EVALUATE 
/ADDRESS command, as described in Section 4.1.10. The EVALUATE and 
EVALUATE/ADDRESS commands both display the address of an address 
expression when the language is set to BLISS. 


4.1.5.2 Numeric Type Conversion by the Debugger 


When evaluating language expressions involving numeric types of different 
precision, the debugger first converts lower-precision types to higher-precision 
types before performing the evaluation. In the following example, the debugger 
converts the integer 1 to the real 1.0 before doing the addition. 

DBG> EVALUATE 1.5+1 

2.5 

DBG> 

The basic rules are as follows. If integer and real types are mixed, the integer 
type is converted to the real type. If integer types of different sizes are mixed 
(for example, byte-integer and word-integer), the one with the smaller size is 
converted to the larger size. If real types of different sizes are mixed (for example, 
G_float and H_float), the one with the smaller size is converted to the larger size. 

In general, the debugger allows more numeric type conversion than the 
programming language. In addition, the hardware type used for a debugger 
calculation (word, longword, Gjfloat, and so on) might differ from that chosen by 
the compiler. Because the debugger is not as strongly typed or as precise as some 
languages, the evaluation of an expression by the EVALUATE command might 
differ from the result that would be calculated by compiler generated code and 
obtained with the EXAMINE command. 


4.1.6 Address Expressions Compared to Language Expressions 

Do not confuse address expressions with language expressions. An address 


expression specifies a program location , whereas a language expression specifies 
a value . In particular, the EXAMINE command expects an address expression as 
its parameter, and the EVALUATE command expects a language expression as its 
parameter. These points are illustrated in the next examples. 

In the following example, the value 12 is deposited into the variable X. This is 
confirmed by the EXAMINE command. The EVALUATE command computes and 
displays the sum of the current value of X and the integer literal 6: 

DBG> DEPOSIT X = 12 
DBG> EXAMINE X 
M0D3\X: 12 
DBG> EVALUATE X + 6 
18 

DBG> 
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In the next example, the EXAMINE command displays the value currently stored 
at the memory location that is 6 bytes beyond the address of X. 

DBG> EXAMINE X + 6 
MOD3\X+6: 274903 
DBG> 

In this case the location is not associated with a compiler generated type. 
Therefore, the debugger interprets and displays the value stored at that location 
in the type longword integer (see Section 4.1.4). 

In the next example, the value of X + 6 (that is, 18) is deposited into the location 
that is 6 bytes beyond the address of X. This is confirmed by the last EXAMINE 
command. 

DBG> EXAMINE X 
MOD3\X: 12 

DBG> DEPOSIT X + 6 = X + 6 

DBG> EXAMINE X 

MOD3\X: 12 

DBG> EXAMINE X + 6 

MOD3\X+6: 18 

DBG> 


4.1.7 Specifying the Current, Previous, and Next Entity 

When using the EXAMINE and DEPOSIT commands, you can use three special 
built-in symbols (address expressions) to refer quickly to the current, previous, 
and next data locations (logical entities). These are the period (.), the circumflex 
( A ), and the Return key. 

The period (.), when used by itself with an EXAMINE or DEPOSIT command, 
denotes the current entity—that is, the program location most recently referenced 
by an EXAMINE or DEPOSIT command. For example: 

DBG> EXAMINE X 
SIZE\X: 7 

DBG> DEPOSIT . = 12 
DBG> EXAMINE . 

SIZE\X: 12 
DBG> 


The circumflex ( A ) and Return key denote, respectively, the previous and next 
logical data locations relative to the last EXAMINE or DEPOSIT command (the 
logical predecessor and successor, respectively). The circumflex and Return key 
are useful for referring to consecutive indexed components of an array. The 
following example illustrates the use of these operators with an array of integers, 
ARR: 


DBG> EXAMINE ARR(5) 
MAIN\ARR(5): 448670 
DBG> EXAMINE A 
MAIN\ARR(4): 792802 
DBG> EXAMINE I Return | 
MAIN\ARR(5): 448670 
DBG> EXAMINE I Return] 
MAIN\ARR(6): 891236 
DBG> 


Examine element 5 of array ARR 
Examine the previous element (4) 
! Examine the next element (5) 

! Examine the next element (6) 


The debugger uses the type associated with the current entity to determine 
logical successors and predecessors. 


4-8 






Examining and Manipulating Program Data 

4.1 General Concepts 

You can also use the built-in symbols %CURLOC, %PREVLOC, and %NEXTLOC 
to achieve the same purpose as the period, circumflex, and Return key, 
respectively. These symbols are useful in command procedures and also if 
your program uses the circumflex for other purposes. Moreover, using the Return 
key to signify the logical successor does not apply to all contexts. For example, 
you cannot press the Return key after typing the DEPOSIT command to indicate 
the next location, whereas you can always use the symbol %NEXTLOC for that 
purpose. 

Note that, like EXAMINE and DEPOSIT, the EVALUATE/ADDRESS command 
also resets the values of the current, previous, and next logical-entity built-in 
symbols (see Section 4.1.10). However, you cannot press the Return key after 
typing the EVALUATE/ADDRESS command to indicate the next location. See 
Appendix D for more information about debugger built-in symbols. 

The previous examples illustrate the use of the built-in symbols after referencing 
a symbolic name with the EXAMINE or DEPOSIT command. If you examine or 
deposit into a memory address, that location might or might not be associated 
with a compiler generated type. When you reference a memory address, the 
debugger uses the following convention to determine logical predecessors and 
successors: 

• If the address has a symbolic name (the name of a variable, component of 
a composite variable, routine, and so on), the debugger uses the associated 
compiler generated type. 

• If the address does not have a symbolic name, the debugger uses the type 
longword integer by default. 

As the current entity is reset with new examine or deposit operations, the 
debugger associates each new location with a type in the manner indicated 
to determine logical successors and predecessors. This is shown in the next 
examples. 

Assume that a FORTRAN program has declared three variables, ARY, FLT, and 
BTE: 

• ARY is an array of three word integers (2 bytes each). 

• FLT is an F_floating type (4 bytes). 

• BTE is a byte integer (1 byte). 

Assume that storage for these variables has been allocated at consecutive 
addresses in memory, starting with 1000. For example: 

1000: ARY(l) 

1002: ARY(2) 

1004: ARY(3) 

1006: FLT 
1010: BTE 
1011: undefined 
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Then, examining successive logical data locations would give the following results: 


DBG> EXAMINE 1000 
MOD3\ARY(1): 13 

DBG> EXAMINE |r55^1 
MOD3\ARY(2): 7 

DBG> EXAMINE I Return 1 
MOD3\ARY(3): 19 

DBG> EXAMINE 
MOD3\FLT: 1.9117807E+07 
DBG> EXAMINE [Riui^ 
MOD3\BTE: 43 

DBG> EXAMINE |R55m1 
1011: 17694732 
DBG> 


! Examine ARY(1), associated with 1000. 
! Current entity is now ARY(1). 

! Examine next location, ARY(2), 

! using type of ARY(1) as reference. 

! Examine next location, ARY(3). 

! Current entity is now ARY(3). 

! Examine entity at 1006 (FLT). 

! Current entity is now FLT. 

! Examine entity at 1010 (BTE). 

! Current entity is now BTE. 

! Examine entity at 1011 (undefined). 
! Interpret data as longword integer. 

! Location is not symbolized. 


The same principles apply when you use type qualifiers with the EXAMINE 
and DEPOSIT commands (see Section 4.5.2). The type specified by the qualifier 
determines the data boundary of an entity and, therefore, any logical successors 
and predecessors. 


4.1.8 Language Dependencies and the Current Language 

The debugger enables you to set your debugging context to any one of several 
VAX-supported languages. The setting of the current language determines 
how the debugger parses and interprets the names, numbers, operators, and 
expressions you specify in debugger commands, and how it displays data. 

By default, the current language is the language of the module containing the 
main program, and it is identified when you invoke the debugger. For example: 

$ PASCAL/NOOPTIMIZE/DEBUG FORMS 
$ LINK/DEBUG FORMS 
$ RON FORMS 

VAX DEBUG Version 5.5 

%DEBUG-I-INITIAL, language is PASCAL, module set to 'FORMS' 

DBG> 

When debugging modules whose code is written in other languages, you can 
use the SET LANGUAGE command to establish a new language dependent 
context. Section 9.3 highlights some important language differences. Appendix E 
summarizes debugger support for languages. See also the documentation supplied 
with a particular language. 


4.1.9 Specifying a Radix for Entering or Displaying Integer Data 

The debugger can interpret and display integer data in any one of four radixes: 
decimal, hexadecimal, octal, and binary. The default radix is decimal for all 
languages except BLISS and MACRO, and it is hexadecimal for BLISS and 
MACRO. 

You can control the radix for the following kinds of integer data: 

• Data that you specify in address expressions or language expressions. 

• Data that is displayed by the EVALUATE and EXAMINE commands. 

You cannot control the radix for other kinds of integer data. For example, 
addresses are always displayed in hexadecimal radix in a SHOW CALLS display. 
Or, when specifying an integer n with various command qualifiers (/AFTER:n, 
/UP:n, and so on) you must use decimal radix. 
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The technique you use to control radix depends on your objective, lb establish 
a new radix for all subsequent commands, use the SET RADIX command. For 
example: 

DBG> SET RADIX HEXADECIMAL 

After this command is executed, all integer data that you enter in address or 
language expressions is interpreted as being hexadecimal. Also, all integer data 
displayed by EVALUATE and EXAMINE commands is given in hexadecimal 
radix. 

The SHOW RADIX command identifies the current radix (which is either the 
default radix, or the radix last established by a SET RADIX command). For 
example: 

DBG> SHOW RADIX 
input radix: hexadecimal 
output radix: hexadecimal 
DBG> 

The SHOW RADIX command identifies both the input radix (for data entry) 
and the output radix (for data display). The SET RADIX command qualifiers 
/INPUT and /OUTPUT enable you to specify different radixes for data entry and 
display. See the command dictionary for additional information about the SET 
RADIX command. 

Use the CANCEL RADIX command to restore the default radix. 

The examples that follow show several techniques for displaying or entering 
integer data in another radix without changing the current radix. 

To convert some integer data to another radix without changing the current 
radix, use the EVALUATE command with a radix qualifier (/BINARY, /DECIMAL, 
/HEXADECIMAL, /OCTAL). For example: 

DBG> SHOW RADIX 
input radix: decimal 
output radix: decimal 
DBG> EVALUATE 18 + 5 

23 ! 23 is decimal integer. 

DBG> EVALUATE/HEX 18+5 

00000017 ! 17 is hexadecimal integer. 

DBG> 

The radix qualifiers do not affect the radix for data entry. 

To display the current value of an integer variable (or the contents of a program 
location that has an integer type) in another radix, use the EXAMINE command 
with a radix qualifier. For example: 

DBG> EXAMINE X 
MOD4\X: 4398 
DBG> EXAMINE/OCTAL . 

MOD4\X: 00000010456 
DBG> 

To enter one or more integer literals in another radix without changing the 
current radix, use one of the radix built-in symbols %BIN, %DEC, %HEX, or 
%OCT. A radix built-in symbol directs the debugger to treat an integer literal 
that follows (or all numeric literals in a parenthesized expression that follows) as 
a binary, decimal, hexadecimal, or octal number, respectively. These symbols do 
not affect the radix for data display. For example: 


! 4398 is a decimal integer. 
! X is the current entity. 

! 10456 is an octal integer. 
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DBG> SHOW RADIX 
input radix: decimal 
output radix: decimal 
DBG> EVAL %BIN 10 
2 

DBG> EVAL %HEX (10 + 10) 
32 

DBG> EVAL %HEX 20 + 33 
65 

DBG> EVAL/HEX %OCT 4672 


! Evaluate the binary integer 10. 

! 2 is a decimal integer. 

! Evaluate the hexadecimal integer 20. 

! 32 is a decimal integer. 

! Treat 20 as hexadecimal, 33 as decimal. 
! 65 is a decimal integer. 

! Treat 4672 as octal and display in hex. 


000009BA 

DBG> EXAMINE X + %DEC 12 
MOD3\X+12: 493847 

DBG> DEPOS J = %OCT 7777777 
DBG> EXAMINE . 

MOD3\J: 2097151 
DBG> EXAMINE/OCTAL . 

MOD3\J: 00007777777 
DBG> EXAMINE %HEX 0A34D 
SHARE$LIBRTL+4941: 344938193 
DBG> 


! 9BA is a hexadecimal number. 

! Examine the location 12 decimal bytes 
! beyond the address of X. 

! Deposit an octal value. 

! Display that value in decimal radix. 

! Display that value in octal radix. 

! Examine location A34D, hexadecimal. 

! 344938193 is a decimal integer. 


__ Note --- 

When specifying a hexadecimal integer that starts with a letter rather 
than a number (for example, A34D in the last example), add a leading 
"0". Otherwise, the debugger tries to interpret the integer as a symbol 
declared in your program. 


See Appendix D for more examples showing the use of the radix built-in symbols. 

4.1.10 Obtaining and Symbolizing Memory Addresses 

Use the EVALUATE/ADDRESS command to determine the memory address 
or the register name associated with a symbolic address expression, such as a 
variable name, line number, routine name, or label. For example: 

DBG> EVALUATE/ADDRESS X ! A variable name 

2476 

DBG> EVALUATE/ADDRESS SWAP ! A routine name 
1536 

DBG> EVALUATE/ADDRESS %LINE 26 

1629 

DBG> 

The address is displayed in the current radix (as defined in Section 4.1.9). You 
can specify a radix qualifier to display the address in another radix. For example: 

DBG> EVALUATE/ADDRESS/HEX X 

000009AC 

DBG> 

If a variable is associated with a register instead of a memory address, the 
EVALUATE/ADDRESS command displays the name of the register, regardless of 
whether a radix qualifier is used. The following command indicates that variable 
K (a nonstatic variable) is associated with register R2: 

DBG> EVALUATE/ADDRESS K 

%R2 

DBG> 
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Like the EXAMINE and DEPOSIT commands, EVALUATE/ADDRESS resets 
the values of the current, previous, and next logical-entity built-in symbols (see 
Section 4.1.7). Unlike the EVALUATE command, EVALUATE/ADDRESS does not 
affect the current-value built-in symbols, %CURVAL and backslash (\ ). 

The SYMBOLIZE command does the reverse of EVALUATE/ADDRESS, but 
without affecting the current, previous, or next logical-entity built-in symbols. It 
converts a memory address or a register name into its symbolic representation 
(including its path name) if such a representation is possible (Chapter 5 explains 
how to control symbolization). For example, the following command shows that 
variable K is associated with register R2: 

DBG> SYMBOLIZE %R2 
address MOD3\%R2: 

M0D3\K 

DBG> 

By default, symbolic mode is in effect (SET MODE SYMBOLIC). Therefore the 
debugger displays all addresses symbolically, if symbols are available for the 
addresses. For example, if you specify a numeric address with the EXAMINE 
command, the address is displayed in symbolic form if symbolic information is 
available: 

DBG> EVALUATE/ADDRESS X 
2476 

DBG> EXAMINE 2476 
M0D3\X: 16 

DBG> 

However, if you specify a register that is associated with a variable, the 
EXAMINE command does not convert the register name to the variable name. 

For example: 

DBG> EVALUATE/ADDRESS K 
%R2 

DBG> EXAMINE IR2 
MOD3\%R2: 78 

DBG> 

By entering the SET MODE NOSYMBOLIC command, you disable symbolic mode 
and cause the debugger to display numeric addresses rather than their symbolic 
names. When symbolization is disabled, the debugger might process commands 
somewhat faster because it does not need to convert numbers to names. The 
EXAMINE command has a /[NOJSYMBOLIC qualifier that enables you to control 
symbolization for a single EXAMINE command. For example: 

DBG> EVALUATE/ADDRESS Y 
512 

DBG> EXAMINE 512 
M0D3\Y: 28 

DBG> EXAMINE/NOSYMBOLIC 512 

512: 28 

DBG> 

Symbolic mode also affects the display of instructions. For example: 

DBG> EXAMINE/INSTRUCTION .%PC 
M0D5ULINE 14+2: MOVAL L A M0D4\X,R11 
DBG> EXAMINE/NOSYMBOL/INSTRUCTION .%PC 
1538: MOVAL L A 1080,R11 

DBG> 
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4.2 Examining and Depositing into Variables 

The examples in this section illustrate how to use the EXAMINE and DEPOSIT 
commands with variables. 

Languages differ in the types of variables they use, the names for these types, 
and the degree to which different types can be intermixed in expressions. The 
following generic types are discussed in this section. 

• Scalars (such as integer, real, character, or Boolean) 

• Strings 

• Arrays 

• Records 

• Pointers (access types) 

The most important consideration when examining and manipulating variables in 
high-level language programs is that the debugger recognizes the names, syntax, 
type constraints, and scoping rules of the variables in your program. Therefore, 
when specifying a variable with the EXAMINE or DEPOSIT command, you use 
the same syntax that is used in the source code. The debugger processes and 
displays the data accordingly. Similarly, when assigning a value to a variable, the 
debugger follows the typing rules of the language. It issues a diagnostic message 
if you try to deposit an incompatible value. The examples in this section show 
some of these invalid operations and the resulting diagnostics. 

When using the DEPOSIT command (or any other command), note the following 
behavior. If the debugger issues a diagnostic message with a severity level of I 
(informational), the command is still executed (the deposit is made in this case). 
The debugger aborts an illegal command line only when the severity level of the 
message is W (warning) or greater. 

See Appendix E and the language documentation for additional language-specific 
information. 

4.2.1 Scalar Types 

The following examples illustrate use of the EXAMINE, DEPOSIT, and 
EVALUATE commands with some integer, real, and Boolean types. 

Examine a list of three integer variables: 

DBG> EXAMINE WIDTH, LENGTH, AREA 

SIZENWIDTH: 4 

SIZEUENGTH: 7 

SIZE\AREA: 28 

DBG> 

Deposit an integer expression: 

DBG> DEPOSIT WIDTH = CURRENT_WIDTH + 10 
DBG> 

The debugger checks that a value to be assigned is compatible with the data type 
and dimensional constraints of the variable. The following example shows an 
attempt to deposit an out-of-bounds value (X was declared as a positive integer): 

DBG> DEPOSIT X = -14 

%DEBUG-I-IVALOUTBNDS, value assigned is out of bounds at or near DEPOSIT 
DBG> 
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If you try to mix numeric types (integer and real of varying precision) in a 
language expression, the debugger generally follows the rules of the language. 
Strongly typed languages do not allow much if any mixing. With some languages, 
you can deposit a real value into an integer variable. However, the real value is 
converted into an integer. For example: 

DBG> DEPOSIT I = 12345 

DBG> EXAMINE I 

M0D3\I: 12345 

DBG> DEPOSIT I = 123.45 

DBG> EXAMINE I 

M0D3\I: 123 

DBG> 

Note that, if numeric types are mixed in an expression, the debugger performs 
type conversion as discussed in Section 4.1.5.2. For example: 

DBG> DEPOSIT Y = 2.356 ! Y is of type D floating point. 

DBG> EXAMINE Y 
M0D3\Y: 2.35600000000000 
DBG> EVALUATE Y + 3 
5.35600000000000 

DBG> DEPOSIT R = 5.35E3 ! R is of type F floating point. 

DBG> EXAMINE R 
MOD3\R: 5350.000 
DBG> EVALUATE R*50 
267500.0 

DBG> DEPOSIT I = 22222 
DBG> EVALUATE R/I 
0.2407524 
DBG> 

The next example shows some operations with Boolean variables. The values 
TRUE and FALSE are assigned to the variables WILLING and ABLE, 
respectively. The EVALUATE command then obtains the logical conjunction 
of these values: 

DBG> DEPOSIT WILLING = TRUE 
DBG> DEPOSIT ABLE = FALSE 
DBG> EVALUATE WILLING AND ABLE 
False 
DBG> 

4.2.2 ASCII String Types 

When displaying an ASCII string value, the debugger encloses it within quotation 
marks (") or apostrophes ('), depending on the language syntax. 

For example: 

DBG> EXAMINE EMPLOYEE_NAME 

PAYROLL\EMPLOYEE_NAME: "Peter C. Lombardi" 

DBG> 

To deposit a string value (including a single character) into a string variable, you 
must enclose the value in quotation marks (") or apostrophes ('). For example: 

DBG> DEPOSIT PART NUMBER = "WG-7619.3-84" 

DBG> 

If the string has more ASCII characters (1 byte each) than can fit into the location 
denoted by the address expression, the debugger truncates the extra characters 
from the right and issues the following message: 

% DEBUG-1-1S TRTRU, string truncated at or near DEPOSIT 
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If the string has fewer characters, the debugger pads the remaining characters to 
the right of the string by inserting ASCII space characters. 

4.2.3 Array Types 

You can examine an entire array aggregate, a single indexed element, or a slice 
(a range of elements). But you can deposit into only one element at a time. The 
following examples show typical operations with arrays. 

The following command displays the values of all the elements of the array 
variable ARRX, a one-dimensional array of integers: 

DBG> EXAMINE ARRX 
MOD3\ARRX 


(1) 

42 

(2) 

17 

(3) 

278 

(4) 

56 

(5) 

113 

(6) 

149 


DBG> 

The following command displays the value of element 4 of array ARRX (depending 
on the language, parentheses or brackets are used to denote indexed elements): 

DBG> EXAMINE ARRX(4) 

MOD3\ARRX(4): 56 

DBG> 

The following command displays the values of all the elements in a slice of ARRX. 
This slice consists of the range of elements from element 2 to element 5: 

DBG> EXAMINE ARRX(2:5) 

MOD3\ARRX 

(2) : 17 

(3) : 278 

(4) : 56 

(5) : 113 

DBG> 

In general, a range of values to be examined is denoted by two values separated 
by a colon {valuel:value2). Depending on the language, two periods (..) can be 
used instead of a colon. 

You can deposit a value to only a single array element at a time (you cannot 
deposit to an array slice or an entire array aggregate with a single DEPOSIT 
command). For example, the following command deposits the value 53 into 
element 2 of ARRX: 

DBG> DEPOSIT ARRX(2) = 53 
DBG> 

The following command displays the values of all the elements of array REAL_ 
ARRAY, a two-dimensional array of real numbers (three per dimension): 

DBG> EXAMINE REAL_ARRAY 
P R0G2\REAL_ARRAY 


(1,1): " 

27.01000 

(1,2): 

31.00000 

(1,3): 

12.48000 

(2,1): 

15.08000 

(2,2): 

22.30000 

(2,3): 

18.73000 


DBG> 


4-16 















Examining and Manipulating Program Data 
4.2 Examining and Depositing into Variables 


The debugger issues a diagnostic message if you try to deposit to an index value 
that is out of bounds. For example: 

DBG> DEPOSIT REAL_ARRAY(1,4) = 26.13 

%DEBUG-I-SUBOUTBND, subscript 2 is out of bounds, value is 4, 

bounds are 1..3 

DBG> 

Note that, in the previous example the deposit operation was executed because 
the diagnostic message is of I level. This means that the value of some array 
element adjacent to (1,3), possibly (2,1) might have been affected by the out-of- 
bounds deposit operation. 

To deposit the same value to several components of an array, you can use a 
looping command, such as FOR or REPEAT. For example, assign the value RED 
to elements 1 to 4 of the array COLOR_ARRAY: 

DBG> FOR I = 1 TO 4 DO (DEPOSIT COLOR ARRAY(I) = RED) 

DBG> 

You can also use the built-in symbols (.) and ( A ) and the Return key to step 
through array elements, as explained in Section 4.1.7. 

4.2.4 Record Types 

You can examine an entire record aggregate, a single record component, or 
several components. But you can deposit into only one component at a time. The 
following examples show typical operations with records. 

The following command displays the values of all the components of the record 
variable PART: 

DBG> EXAMINE PART 
INVENTORY\PART: 

ITEM: "WF-1247" 

PRICE: 49.95 

IN_STOCK: 24 

DBG> 

The following command displays the value of component INJ3TOCK of record 
PART (general syntax): 

DBG> EXAMINE PART.IN_STOCK 
INVENTORY\PART.IN_STOCK: 2 4 
DBG> 

The following command displays the value of the same record component, using 
COBOL syntax (the language must be set to COBOL): 

DBG> EXAMINE IN_STOCK OF PART 
INVENTORY\IN_STOCK of PART: 

IN_STOCK: 24 

DBG> 

The following command displays the values of two components of record PART: 

DBG> EXAMINE PART.ITEM, PART.IN_ST0CK 
INVENTORY\PART.ITEM: "WF-1247" 

INVENTORY\PART.IN_STOCK: 24 
DBG> 

The following command deposits a value into record component IN_STOCK: 

DBG> DEPOSIT PART.IN_STOCK = 17 
DBG> 
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4.2.5 Pointer (Access) Types 

You can examine the entity designated (pointed to) by a pointer variable and 
deposit a value into that entity. You can also examine a pointer variable. 

For example, the following Pascal code declares a pointer variable A that 
designates a value of type real: 


TYPE 

T = A REAL; 

VAR 

A : T; 


The following command displays the value of the entity designated by the pointer 
variable A: 

dbg> examine a a 

M0D3\A A : 1.7 
DBG> 

In the following example, the value 3.9 is deposited into the entity designated by 
A: 

DBG> DEPOSIT A A = 3.9 
DBG> EXAMINE A a 
M0D3\A A : 3.9 
DBG> 

When you specify the name of a pointer variable with the EXAMINE command, 
the debugger displays the memory address of the object it designates. For 
example: 

dbg> examine/hexadecimal a 

SAMPLE\A: 0000B2A4 

DBG> 

4.3 Examining and Depositing VAX Instructions 

__ Note- 

See Chapter 11 for additional information about VAX vector instructions. 


The debugger recognizes address expressions that are associated with VAX 
assembly language instructions. This enables you to examine and deposit 
instructions using the same basic techniques as with variables. 

When debugging at the instruction level, you might find it convenient to first 
enter the following command. It sets the default step mode to stepping by 
instruction: 

DBG> SET STEP INSTRUCTION 
DBG> 
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There are other step modes that enable you to execute the program to specific 
kinds of instructions (INSTRUCTION[(=opcocfe)], CALL, BRANCH, and so on). 
Also you can set breakpoints to interrupt execution on every instruction or on 
instructions of a particular class (SET BREAK/INSTRUCTION[(=opcode), /CALL, 
and so on). 

In addition you can use a screen-mode instruction display (see Section 7.2.4), to 
display the actual decoded instruction stream of your program. 

4.3.1 Examining VAX Instructions 

If you specify an address expression that is associated with an instruction in an 
EXAMINE command (for example, a line number), the debugger displays the first 
instruction at that location. You can then use the period (.), Return key, and 
circumflex character ( A ) to display the current, next, and previous instruction 
(logical entity), as described in Section 4.1.7. For example: 

DBG> EXAMINE %LINE 12 


M0D3ULINE 12: 

DBG> EXAMINE I Return | 

MOVL 

(Rll),B A 16(Rll) 


M0D3\%LINE 12+4: 
DBG> EXAMINE I Return | 

MOVL 

S A #1,B A 4(Rll) ! 

Next instruction. 

M0D3\%LINE 12+8: 
DBG> EXAMINE A 

TSTL 

B A 16(Rll) ! 

Next instruction. 

M0D3ULINE 12+4: 
DBG> 

MOVL 

S A #1,B A 4(Rll) ! 

Previous instruction. 


Line numbers, routine names, and labels are symbolic address expressions that 
are associated with instructions. In addition, instructions might be stored at 
various other memory addresses and in certain registers during the execution of 
your program. 

The program counter (PC) is the register that contains the address of the next 
instruction to be executed by your program. The command EXAMINE .%PC 
displays that instruction. The period (.), when used directly in front of an 
address expression, denotes the "contents of" operator—that is, the contents of 
the location designated by the address expression. Note the following distinction: 

• EXAMINE %PC displays the current PC value, namely the address of the 
next instruction to be executed. 

• EXAMINE .%PC displays the contents of that address, namely the next 
instruction to be executed by the program. 

When you enter the EXAMINE .%PC command, you can control the amount of 
information displayed by using the /OPERANDS qualifier. For example: 

DBG> EXAMINE ,%PC 

M0D3\%LINE 12: MOVL B A 12(R11),R1 

DBG> EXAMINE/OPERANDS .%PC 

M0D3\%LINE 12: MOVL B A 12(R11),R1 

B A 12(Rll) M0D3\K (address 1196) contains 1 
R1 R1 contains 8 

DBG> EXAMINE/OPERANDS=FULL .%PC 
M0D3ULINE 12: MOVL B A 12(R11),R1 

B A 12(Rll) Rll contains M0D3\N (address 1184), B A 12(1184) evaluates to 
M0D3\K (address 1196), which contains 1 
R1 R1 contains 8 

DBG> 
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Use the /OPERANDS qualifier only when examining the current PC instruction. 
The information might not be reliable if you specify other locations. The command 
SET MODE [NO]OPERANDS enables you to control the default behavior of the 
EXAMINE .%PC command. 

As shown in the previous examples, the debugger knows whether an address 
expression is associated with an instruction. If it is, the EXAMINE command 
displays that instruction (you do not need to use the /INSTRUCTION qualifier). 
You use the /INSTRUCTION qualifier to display the contents of an arbitrary 
program location as a VAX instruction—that is, the command EXAMINE 
/INSTRUCTION causes the debugger to interpret and format the contents of 
any program location as a VAX instruction (see Section 4.5.2). 

Note that, when you examine consecutive instructions in a MACRO program, 
the debugger might misinterpret data as instructions if storage for the data is 
allocated in the middle of a stream of instructions. 

The following example shows some MACRO code with two longwords of data 
storage allocated directly after the BRB instruction at line 7 (line numbers have 
been added to the example for clarity): 

module TEST 


1: 

2: 

.TITLE 

TEST 

3: 

TEST$START:: 


4: 

5: 

.WORD 

0 

6: 

MOVL 

#2,R2 

7: 

8: 

BRB 

LABEL_2 

9: 

.LONG 

A X12345 

10: 

11: 

.LONG 

A X14 4 65 

12: 

LABEL 2: 


13: 

14: 

MOVL 

#5,R5 

15: 

.END 

TEST$START 


The following EXAMINE command displays the instruction at the start of fine 6: 

DBG> EXAMINE ILINE 6 

TEST\TEST$START\%LINE 6: MOVL S A #02,R2 

DBG> 

The following EXAMINE command correctly interprets and displays the logical 
successor entity as an instruction, at line 7: 

DBG> EXAMINE IrSu^I 

TEST\TEST$START\%LINE 7: BRB TEST\TEST$START\LABEL_2 

DBG> 

However, the following three EXAMINE commands incorrectly interpret the three 
logical successors as instructions: 

DBG> EXAMINE (rSu^I 

TEST\TEST$START\%LINE 7+2: MULF3 S A #11.00000,S A #0.5625000,S A #0.5000000 
DBG> EXAMINE 

%DEBUG-W-ADDRESSMODE, instruction uses illegal or undefined addressing modes 
TEST\TEST$START\%LINE 7+6: MULD3 S A #0.5625000[R4],S A #0.5000000,@W A 5505(R0) 

DBG> EXAMINE [R^H 
TEST$START+12: HALT 

DBG> 
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4.3.2 Depositing VAX Instructions 

When depositing a VAX instruction, use the following command format: 

DEPOSIT/INSTRUCTION address-expression = " VAX instruction” 

You must enclose the instruction in either quotation marks or apostrophes. You 
must also use the /INSTRUCTION qualifier with the DEPOSIT command, to 
indicate that the delimited string is an instruction and not an ASCII string. Or, 
if you plan to deposit several instructions, you can first enter the SET TYPE 
/OVERRIDE INSTRUCTION command (see Section 4.5.2). You then do not need 
to use the /INSTRUCTION qualifier on the DEPOSIT command. 


VAX instructions occupy different numbers of bytes, depending on their operands. 
When depositing VAX instructions of arbitrary lengths into successive memory 
locations, use the logical successor operator (Return key) to establish the next 
unoccupied location where an instruction can be deposited. The following example 
illustrates the technique. 


DBG> SET TYPE/OVERRIDE/INST ! 

DBG> DEPOSIT 730 = "MOVB #77, Rl"i 

DBG> EXAMINE . i 

730: MOVB #77,R1 
DBG> EXAMINE (Rfr] i 

734: HALT 

DBG> DEPOSIT . = "MOVB #66, R2" ! 

DBG> EXAMINE . I 

734: MOVB #66,R2 
DBG> 


Set the default type to instruction. 

Deposit an instruction beginning at address 730. 
Examine the current entity to verify the deposit. 

Make the logical successor the new current entity. 

Deposit the next instruction. 

Display and verify the deposit. 


When you replace an instruction, be sure that the new instruction, including 
operands, is the same length in bytes as the old instruction. If the new 
instruction is longer, you cannot deposit it without overwriting, and thereby 
destroying, the next instruction. If the new instruction occupies fewer bytes of 
memory than the old one, you must deposit NOP instructions (instructions that 
cause "no operation") in bytes of memory left unoccupied after the replacement. 
The debugger does not warn you if an instruction you are depositing will 
overwrite a subsequent instruction, nor does it remind you to fill in vacant 
bytes of memory with NOPs. 


The following example illustrates how to replace an instruction with an 
instruction of equal length. 


! Step by instruction. 


#1,L A 2224 ! Instruction to be replaced. 


DBG> SET STEP INSTRUCTION 
DBG> STEP 

stepped to 1584: PUSHAL (RU) 
DBG> STEP 

stepped to 1586: CALLS 
DBG> EXAMINE .%PC 
1586: CALLS #1,L A 2224 
DBG> EXAMINE [RitSFfl 
1593: CALLS #0,L A 2216 

DBG> DEPOSIT/INST 1586 = "CALLS 

DBG> EXAMINE . 

1586: CALLS #2,L A 2224 

DBG> EXAMINE 

1593: CALLS #0,L A 2216 

DBG> 


! Determine start of next 
! instruction (1593). 

#2,L A 2224" 

! Deposit new instruction. 

! Verify that instruction 
! is deposited. 

! Verify that the next 
! instruction is unchanged. 
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4.4 Examining and Depositing into Registers 

_ Note - 

See Chapter 11 for information about the VAX vector registers. 


The VAX architecture provides 16 general registers, some of which are used for 
temporary address and data storage. When referencing a register in a debugger 
command, use the following built-in symbols (the register name preceded by a 
percent sign (%)). 


Symbol 

Description 

%R0 ... %R11 

General purpose registers (RO ... Rll) 

%AP (%R12) 

Argument pointer (AP) 

%FP (%R13) 

Frame pointer (FP) 

%SP (%R14) 

Stack pointer (SP) 

%PC (%R15) 

Program counter (PC) 

%PSL 

Processor status longword (PSL) 


You can omit the percent sign (%) prefix if your program has not declared a 
symbol with the same name. 

You can examine the contents of all the registers. You can deposit values into all 
the registers except for SP. Use caution when depositing values into FP. 

The following examples show how to examine and deposit into registers. 


DBG> SHOW TYPE 
type: long integer 
DBG> SHOW RADIX 
input radix: decimal 
output radix: decimal 
DBG> EXAMINE %R11 
M0D3UR11: 1024 

DBG> DEPOSIT %R11 = 444 
DBG> EXAMINE %R11 
Rll: 444 
DBG> EXAMINE %PC 
MODUPC: 1553 
DBG> EXAMINE %SP 
0\%SP: 2147278720 

DBG> 


! Show type for locations without 
! a compiler generated type. 

! Identify current radix. 


! Display value in Rll. 

! Deposit new value into Rll. 

! Check new value. 

! Display value in program counter. 

! Display value in stack pointer. 


See Section 4.3.1 for specific information about the PC. 


4.4.1 The Processor Status Longword (PSL) 

The PSL is a register whose value represents a number of processor state 
variables. The first 16 bits of the PSL (referred to separately as the processor 
status word, or PSW) contain unprivileged information about the current 
processor state. The values of these bits can be controlled by a user program. 
The latter 16 bits of the PSL, bits 16 to 31, contain privileged information and 
cannot be altered by a user-mode program. 
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The following example shows how to examine the contents of the PSL: 

DBG> EXAMINE %PSL 
M0D3\PSL: 

CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV T N Z V C 
n n n n mode mode lv n n nnnnnn 

DBG> 

See the VAX Architecture Handbook for complete information about the PSL, 
including the values of the various bits. 

You can also display the information in the PSL in other formats. For example: 

DBG> EXAMINE/LONG/HEX %PSL 
M0D3UPSL: 03C00010 

DBG> EXAMINE/LONG/BIN %PSL 

M0D3UPSL: 00000011 11000000 00000000 00010000 

DBG> 

The command EXAMINE/PSL displays the value at any location in PSL format. 
This is useful for examining saved PSLs on the call stack. 

To disable all conditions in the PSL, clear bits 0 to 15 with the following 
DEPOSIT command: 

DBG> DEPOSIT/WORD PSL = 0 
DBG> EXAMINE PSL 
MOD3\PSL: 

CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV T N Z V C 
0000 USER USER 0 00000000 

DBG> 

4.5 Specifying a Type When Examining and Depositing 

The preceding sections explain how to use the EXAMINE and DEPOSIT 
commands with program locations that have a symbolic name and, therefore, are 
associated with a compiler generated type. 

Section 4.5.1 describes how the debugger formats (types) data for program 
locations that do not have a symbolic name and explains how you can control the 
type for those locations. 

Section 4.5.2 explains how to override the type associated with any program 
location, including a location that has a symbolic name. 

4.5.1 Defining a Type for Locations Without a Symbolic Name 

Program locations that do not have a symbolic name and, therefore, are not 
associated with a compiler generated type have the type longword integer by 
default. Section 4.1.4 explains how to examine and deposit into such locations 
using the default type. 

The SET TYPE command enables you to change the default type. This is useful 
if you want to examine and display the contents of a location in another type, 
or if you want to deposit a value of some particular type into a location that is 
associated with another type. The possible type keywords are as follows: 
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ASCIC 

CONDITION_VALUE 

INSTRUCTION 

QUADWORD 

ASCID 

D.FLOAT 

LONGWORD 

TYPE =(type-expression) 

ASCII :/i 

DATE.TIME 

OCTAWORD 

WORD 

ASCIW 

FLOAT 

PACKED 


ASCIZ 

G_FLOAT 

PSL 


BYTE 

H_FLOAT 

PSW 



For example, the following commands set the type for locations without a 
symbolic name to, respectively, byte integer, G_float, and ASCII with 6 bytes of 
ASCII data. Each successive SET TYPE command resets the type: 


DBG> SET TYPE BYTE 
DBG> SET TYPE G_FLOAT 
DBG> SET TYPE ASCII:6 

Note that the SET TYPE command, when used without the /OVERRIDE 
qualifier, does not affect the type for program locations that have a symbolic 
name (locations associated with a compiler generated type). 

The SHOW TYPE command identifies the current type for locations without a 
symbolic name, lb restore the default type for such locations, enter the command 
SET TYPE LONGWORD. 


4.5.2 Overriding the Current Type 

The SET TYPE/OVERRIDE command enables you to change the type associated 
with any program location, thereby overriding any compiler generated type. For 
example, after the following command is executed, an unqualified EXAMINE 
command displays the contents of only the first byte of the location specified 
and interprets the contents as byte integer data. An unqualified DEPOSIT 
command modifies only the first byte of the location specified and formats the 
data deposited as byte integer data. 

DBG> SET TYPE/OVERRIDE BYTE 

To identify the current override type, enter the SHOW TYPE/OVERRIDE 
command. To cancel the current override type and restore the normal 
interpretation of locations that have a symbolic name, enter the command 
CANCEL TYPE/OVERRIDE. 


Type qualifiers, used with the EXAMINE and DEPOSIT commands, enable you to 
override the type currently associated with a program location for the duration of 
a single EXAMINE or DEPOSIT command. The type qualifiers are as follows: 


/ASCIC 

/CONDITION..VALUE 

/ASCID 

/D.FLOAT 

/ASCII :n 

/DATE_TIME 

/ASCIW 

/FLOAT 

/ASCIZ 

/G_FLOAT 

/BYTE 

/H.FLOAT 


/INSTRUCTION 

/LONGWORD 

/OCTAWORD 

/PACKED 

/PSL 

/PSW 


/QUADWORD 

/TASK 

/TYPE=(type-expression) 

/WORD 


These qualifiers override any previous SET TYPE or SET TYPE/OVERRIDE 
command as well as any compiler generated type. 
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When used with a type qualifier, the EXAMINE command displays the entity 
specified by the address expression in that type. For example: 

DBG> EXAMINE %LINE 15 ! Display line 15 in compiler 

M0D3\fiLINE 15 : MOVL #1,B A 44(R11) ! generated type: instruction. 

DBG> EXAMINE/BYTE . ! Type is byte integer. 

M0D3ULINE 15 : -48 

DBG> EXAMINE/WORD . ! Type is word integer. 

M0D3ULINE 15 : 464 

DBG> EXAMINE/LONG . ! Type is longword integer. 

M0D3\%LINE 15 : 749404624 

DBG> EXAMINE/QUAD . ! Type is quadword integer. 

MOD3%LINE 15 : +0130653502894178768 

DBG> EXAMINE/FLOAT . | Type is F floating. 

MOD3%LINE 15 : 1.9117807E-38 

DBG> EXAMINE/G_FLOAT . ! Type is G floating. 

MOD3ILINE 15 : 1.509506018605227E-300 

DBG> EXAMINE/INSTRUCTION . ! Type is VAX instruction. 

MOD3ULINE 15 : MOVL #1,B A 44(R11) 

DBG> EXAMINE/ASCII . ! Type is ASCII string. 

MOD3\%LINE 15 : 

DBG> 

When used with a type qualifier, the DEPOSIT command deposits a value of that 
type into the location specified by the address expression, overriding the type 
associated with the address expression. 

The remaining sections provide examples of specifying integer, string, and 
user-declared types with type qualifiers and the SET TYPE command. 

4.5.2.1 Integer Types 

The following examples illustrate the use of the EXAMINE and DEPOSIT 
commands with integer type qualifiers (/BYTE, /WORD, /LONGWORD). These 
qualifiers enable you to deposit a value of a particular integer type into an 
arbitrary program location. 


DBG> SHOW TYPE 
type: long integer 
DBG> EVALU/ADDR . 

724 

DBG> DEPO/BYTE . = 1 

DBG> EXAM . 

724: 1280461057 

DBG> EXAM/BYTE . 

724: 1 

DBG> DEPO/WORD . = 2 

DBG> EXAM/WORD . 

724: 2 

DBG> DEPO/LONG 724 = 999 

DBG> EXAM/LONG 724 

724: 999 

DBG> 


! Show type for locations without 
! a compiler generated type. 

! Current location is 724. 

! Deposit the value 1 into one byte 
! of memory at address 724. 

! By default, 4 bytes are examined. 

! Examine one byte only. 

! Deposit the value 2 into first two 
! bytes (word) of current entity. 

! Examine a word of the current entity. 

! Deposit the value 999 into 4 bytes 
!(a longword) beginning at address 724. 

! Examine 4 bytes (longword) 

! beginning at address 724. 
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4.5.2.2 ASCII String Type 

The following examples illustrate the use of the EXAMINE and DEPOSIT 
commands with the /ASCII:ra type qualifier. 

When used with the DEPOSIT command, this qualifier enables you to deposit 
an ASCII string of length n into an arbitrary program location. In the example, 
the location has a symbolic name (I) and, therefore, is associated with a compiler 
generated integer type. The command format is as follows: 

DEPOSIT/ASCII:n address-expression = "ASCII string of length ri' 

The default value of n is 4 bytes. 


DBG> DEPOSIT I = "abode" ! I has compiler generated integer type. 
%DEBUG-W-INVNUMBER, invalid numeric string 'abcde' 

! So, cannot deposit string into I. 

DBG> DEP/ASCII-.5 I = "abcde"! /ASCII qualifier overrides integer 

! type to deposit 5 bytes of 


DBG> EXAMINE . 
M0D3\I: 1146048327 

DBG> EXAM/ASCII:5 . 
MOD3\I: "abcde" 
DBG> 


! ASCII data. 

! Display value of I in compiler 
! generated integer type. 

! Display value of I as 5-byte 
! ASCII string. 


If you want to enter several DEPOSIT/ASCII commands, you can establish an 
override ASCII type with the SET TYPE/OVERRIDE command. Subsequent 
EXAMINE and DEPOSIT commands then have the effect of specifying the /ASCII 
qualifier with these commands. For example: 


DBG> SET TYPE/OVER ASCII:5 ! Establish ASCII:5 as override type.) 
DBG> DEPOSIT I = "abcde" ! Can now deposit 5-byte string into I.) 
DBG> EXAMINE I ! Display value of I as 5-byte) 

MOD3\I: "abcde" ! ASCII string. 

DBG> CANCEL TYPE/OVERRIDE ! Cancel ASCII override type. 

DBG> EXAMINE I ! Display I in compiler generated type. 

MOD3\I: 1146048327 

DBG> 


4.5.2.3 User-Declared Types 

The following examples illustrate the use of the EXAMINE and DEPOSIT 
commands with the fTYPE=(name) qualifier. The qualifier enables you to specify 
a user-declared override type when examining or depositing. 

For example, assume that a Pascal program contains the following code, which 
declares the enumeration type COLOR with the three values RED, GREEN, and 
BLUE: 


TYPE 

COLOR = (RED,GREEN,BLUE); 


During the debugging session, the SHOW SYMBOL/TYPE command identifies 
the type COLOR as it is known to the debugger: 

DBG> SHOW SYMBOL/TYPE COLOR 
data MOD3\COLOR 

enumeration type (COLOR, 3 elements), size: 1 byte 

DBG> 
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The next command displays the value at address 1000, which is not associated 
with a symbolic name. Therefore, the value 0 is displayed in the type longword 
integer, by default: 

DBG> EXAMINE 1000 
1000: 0 
DBG> 

The next command displays the value at address 1000 in the type COLOR. The 
preceding SHOW SYMBOL/TYPE command indicates that each enumeration 
element is stored in 1 byte. Therefore, the debugger converts the first byte of the 
longword integer value 0 at address 1000 to the equivalent enumeration value, 
RED (the first of the three enumeration values): 

DBG> EXAMINE/TYPE=(COLOR) 1000 

1000: RED 

DBG> 

The following DEPOSIT command deposits the value GREEN into address 1000 
with the override type COLOR. The EXAMINE command displays the value at 
address 1000 in the default type, longword integer: 

DBG> DEPOSIT/TYPE=(COLOR) 1000 = GREEN 
DBG> EXAMINE 1000 
1000: 1 
DBG> 

The following SET TYPE command establishes the type COLOR for locations, 
such as address 1000, that do not have a symbolic name. The EXAMINE 
command now displays the value at 1000 in the type COLOR: 

DBG> SET TYPE TYPE=(COLOR) 

DBG> EXAMINE 1000 
1000: GREEN 

DBG> 
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_5 

Controlling Access to Symbols in Your 

Program 


Symbolic debugging enables you to specify variable names, routine names, and so 
on, precisely as they appear in your source code. You do not need to use numeric 
memory addresses or registers when referring to program locations, although you 
can, if you want. 

In addition, you can use symbols in the context that is appropriate for the 
program and its source language. The debugger supports the language 
conventions regarding data types, expressions, scope and visibility of entities, and 
so on. 

To have full access to the symbols that are associated with your program, you 
must compile and link the program using the /DEBUG command qualifier. 

Under these conditions, the way in which symbol information is passed from your 
source program to the debugger and is processed by the debugger is transparent 
to you in most cases. However, certain situations might require some action. 

For example, when you try to set a breakpoint on a routine named COUNTER, 
the debugger might display the following diagnostic message: 

DBG> SET BREAK COUNTER 

% DEBUG-E-NOSYMBOL, symbol 'COUNTER' is not in the symbol table 
DBG> 

You must then set the module where COUNTER is defined, as explained in 
Section 5.2. 

Or, the debugger might display the following message if the same symbol X is 
defined (declared) in more than one module, routine, or other program unit: 

DBG> EXAMINE X 

IDEBUG-E-NOUNIQUE, symbol 'X' is not unique 
DBG> 

You must then resolve the symbol ambiguity, perhaps by specifying a path name 
for the symbol, as explained in Section 5.3. 

This chapter explains how to handle these and other situations related to 
accessing symbols in your program. 

The chapter discusses only the symbols (typically address expressions) that are 
derived from your source program, for example: 

• The names of entities that you have declared in your source code, such as 
variables, routines, labels, array elements, or record components. 

• The names of modules (compilation units) and shareable images that are 
linked with your program. 
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• Elements that the debugger uses to identify source code—for example, the 
specifications of source files, and source line numbers as they appear in a 
listing file or when the debugger displays source code. 

The following types of symbols are discussed in other chapters: 

• The symbols you create during a debugging session with the DEFINE 
command are covered in Section 8.4. 

• The debugger’s built-in symbols, such as the period (.) and %PC are 
tabulated in Appendix D and discussed throughout this manual in the 
appropriate context. 

Also, see Section 4.1.10 for information about how to obtain the memory 
addresses and register names associated with symbolic address expressions and 
how to symbolize program locations. 


_ Note -—— 

If your program was optimized during compilation, certain variables 
in the program might be removed by the compiler. If you then try to 
reference such a variable, the debugger issues a warning (see Section 5.1 
and Section 9.1). 

Before you try to reference a nonstatic (stack-local or register) variable, 
its defining routine must be active on the call stack. That is, program 
execution must be suspended somewhere within the defining routine (see 
Section 3.6.2). 


5.1 Controlling Symbol Information When Compiling and Linking 

To take full advantage of symbolic debugging, you must compile and link 
your program with the /DEBUG qualifier. The following example illustrates 
these steps with a simple Pascal program, INVENTORY, that consists of two 
compilation units whose source code is in two separate files, FORMS.PAS and 
INVENTORY.PAS. INVENTORY is the main program unit: 

$ PASCAL/NOOPTIMIZE/DEBUG FORMS, INVENTORY 
$ LINK/DEBUG INVENTORY, FORMS 

Note that the /NOOPTIMIZE qualifier is used with the compiler command 
(PASCAL, in this example). If the compiler optimizes code by default, it is best 
to disable this feature by specifying /NOOPTIMIZE (or the equivalent qualifier, if 
any, for your compiler). Otherwise, the resulting object code is optimized, possibly 
causing the contents of some program locations to be inconsistent with what you 
might expect from looking at the source code. (Section 9.1 describes some of the 
effects of optimization.) 

The next sections describe how symbol information is created and passed to the 
debugger when compiling and linking. 
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5.1.1 Compiling 

When you compile a source file using the /DEBUG qualifier, the compiler creates 
symbol records for the debug symbol table (DST records) and includes them in 
the object module being generated (such as the compiler output file FORMS.OBJ, 
in the previous example). 

DST records provide not only the names of symbols but also all relevant 
information about their use. For example: 

• Data types, ranges, constraints, and scopes associated with variables. 

• Parameter names and parameter types associated with functions and 
procedures. 

• Source line correlation records, which associate source lines with line numbers 
and source files. 

Most compilers allow you to vary the amount of DST information put in an object 
module by specifying different options with the /DEBUG qualifier. Table 5-1 
identifies the options for most compilers (refer to the documentation supplied 
with your compiler for complete information). 


Table 5-1 Compiler Options for DST Symbol Information 


Compiler Command Qualifier 

DST Information in Object Module 

/DEBUG 1 

Full 

/DEBUG=TRACEBACK 2 

Traceback only (module names, routine names, and 
line numbers) 

/NODEBUG 3 

None 


1 /DEBUG, /DEBUG=ALL, and /DEBUG=(SYMBOLS,TRACEBACK) are equivalent. 

2 /DEBUG=TRACEBACK and DEBUG=(NOSYMBOLS,TRACEBACK) are equivalent. 

3 /NODEBUG, /DEBUG=NONE, and /DEBUG=(NOSYMBOLS,NOTRACEBACK) are equivalent. 


The TRACEBACK option is a default for most compilers. That is, if you omit 
the /DEBUG qualifier, most compilers assume /DEBUG=TRACEBACK. The 
TRACEBACK option enables the VMS traceback condition handler to translate 
memory addresses into routine names and line numbers so that it can give a 
symbolic traceback if a run-time error has occurred. For example: 

$ RUN INVENTORY 


IPAS-F-ERRACCFIL, error in accessing file PAS$OUTPUT 
%PAS-F-ERROPECRE, error opening/creating file 
IRMS-F-FNM, error in file name 
%TRACE-F-TRACEBACK, symbolic stack dump follows 

module name routine name line rel PC abs PC 


PAS$IO_BASIC _PAS$C0DE 
PAS$IO_BASIC _PAS$CODE 
PAS$IO_BASIC _PAS$CODE 
INVENTORY INVENTORY 
$ 


00000192 00001CED 

0000054D 000020A8 

0000028B 00001DE6 

59 00000020 000005A1 


Traceback information is also used by the debugger’s SHOW CALLS command. 
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5.1.2 Local and Global Symbols 

DST records contain information about all of the symbols that are defined in your 
program. These are either local or global symbols. 

Typi call y a local symbol is a symbol that is referenced only within the module 
where it is defined; a global symbol is a symbol such as a routine name, 
procedure entry point, or a global data name, that is defined in one module but 
referenced in other modules. 

A global symbol that is defined in a shareable image and is referenced in 
another image (for example the main, executable, image of a program) is called a 
uni versal symbol. When creating a shareable image, you must explicitly define 
an y universal symbols as such at link time. See Section 5.4 for information about 
universal symbols and shareable images. 

Generally, the compiler resolves references to local symbols, and the linker 
resolves references to global symbols. 

The distinction between local and global symbols is discussed in various parts of 
this chapter in connection with symbol lookup and with shareable images and 
universal symbols. 

5.1.3 Linking 

When you enter the LINK/DEBUG command to link object modules and produce 
an executable image, the linker performs several functions that affect debugging: 

• It builds a debug symbol table (DST) from the DST records contained in 
the object modules being linked. The DST is the primary source of symbol 
information during a debugging session. 

• It resolves references to global symbols and builds a global symbol table 
(GST). The GST duplicates some of the global symbol information already 
contained in the DST, but the GST is used by the debugger for symbol lookup 
under certain circumstances. 

• It puts the DST and GST in the executable image. 

• It sets flags in the executable image that cause the image activator to pass 
control to the debugger when you enter the RUN command. 

_ Note- 

Section 5.4 explains how to link shareable images for debugging, including 
how to define universal symbols (global symbols that are defined within a 
shareable image and referenced from another image). 


Table 5—2 summarizes the level of DST and GST information passed to the 
debugger depending on the compiler or LINK command option. The compiler 
command qualifier controls the level of DST information passed to the linker. The 
LINK command qualifier controls not only how much DST and GST information 
is passed to the debugger but also how (or if) you can invoke the debugger. 
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Table 5-2 Effect of Compiler and Linker on DST and GST Symbol Information 


Compiler 

Command 

Qualifier 1 

DST Data in 
Object Module 

LINK Command 
Qualifier 2 

Command to 

Invoke 

Debugger 

DST Data 

Passed 
to Debugger 

GST Data 
Passed 
to Debugger 3 

/DEBUG 

Full 

/DEBUG 

RUN 

Full 

Full 

/DEBUG=TRACE 

Traceback only 

/DEBUG 

RUN 

Traceback only 

Full 

/NODEBUG 

None 

/DEBUG 

RUN 

None 

Full 

/DEBUG 

Full 

/TRACE 4 

RUN/DEBUG 

Traceback only 

Full 

/DEBUG=TRACE 

Traceback only 

/TRACE 

RUN/DEBUG 

Traceback only 

Full 

/NODEBUG 

None 

/TRACE 

RUN/DEBUG 

None 

Full 

/DEBUG 

Full 

/NOTRACE 

Cannot 




1 See Table 5-1 for additional information. 

2 You must also specify the /SHAREABLE qualifier when creating a shareable image (see Section 5.4). 

3 GST data includes global symbol information that is resolved at link time. GST data for an executable image includes 
the names and values of global routines and global constants. GST data for a shareable image includes universal symbols 
(see Section 5.1.2 and Section 5.4). 

4 LINK/TRACEBACK and LINK/NODEBUG are equivalent. This is the default for the LINK command. 


If you specify /NODEBUG with the compiler command and subsequently link and 
execute the image, the debugger issues the following message when it is invoked: 

% DEBUG-1-NOLOCALS, image does not contain local symbols 

The preceding message, which occurs whether you linked with the /TRACEBACK 
or /DEBUG qualifier, indicates that no DST has been created for that image. 
Therefore, you have access only to global symbols contained in the GST. 

If you do not specify /DEBUG with the LINK command, the debugger issues the 
following message when it is invoked: 

%DEBUG-I-NOGLOBALS, some or all global symbols not accessible 

The preceding message indicates that the only global symbol information 
available during the debugging session is information that is stored in the 
DST. 

These concepts are discussed in later sections. In particular, see Section 5.4 for 
additional information related to debugging shareable images. 

5.1.4 Controlling Symbol Information in Debugged Images 

Symbol records occupy space within the executable image. After you have 
debugged your program, you might want to link it again without using the 
/DEBUG qualifier, to make the executable image smaller. This creates an image 
with only traceback data in the DST and with a GST. 

The command LINK/NOTRACEBACK enables you to secure the contents of an 
image from users after it has been debugged. Use this command for images that 
are to be installed with privileges (see the Guide to VMS System Security and the 
Guide to Setting Up a VMS System ). When you enter LINK/NOTRACEBACK, no 
symbolic information (including traceback data) is passed to the image. Moreover, 
the debugger cannot be invoked, either by the RUN/DEBUG command, or by a 
Ctrl/Y-DEBUG sequence while the program is running. 


5-5 








Controlling Access to Symbols in Your Program 
5.2 Setting and Canceling Modules 


5.2 Setting and Canceling Modules 

You need to set a module if the debugger is unable to locate a symbol that you 
have specified (for example, a variable name X) and issues a message as in the 
following example: 

DBG> EXAMINE X 

%DEBUG-E-NOSYMBOL, symbol 'X' is not in the symbol table 
DBG> 

This section explains module setting and the conditions under which you might 
need to set or cancel a module, using the SET MODULE and CANCEL MODULE 
commands. 

Complete symbol information is passed from your program’s source code to the 
debugger when you compile and link the program using the /DEBUG command 
qualifier, as explained in Section 5.1. 

When you invoke the debugger, symbol information is contained in the DST 
and GST, within the executable image. The DST contains detailed information 
about local and global symbols. The GST duplicates some of the global symbol 
information contained in the DST. 

To facilitate symbol searches, the debugger loads symbol information from the 
DST and GST into a run-time symbol table (RST), which is structured for efficient 
symbol lookup. Unless symbol information is in the RST, the debugger does not 
recognize or properly interpret the associated symbol. 

Because the RST takes up memory, the debugger loads it dynamically, 
anticipating what symbols you might want to reference in the course of program 
execution. The loading process is called module setting, because all symbol 
information for a given module is loaded into the RST at one time. 

At debugger startup, all GST records are loaded into the RST because global 
symbols must be accessible throughout the debugging session. Also, the debugger 
sets the module that contains the main program (the routine specified by the 
image transfer address, where execution is suspended at the start of a debugging 
session). You therefore have access to all global symbols and to any local symbols 
that should be visible within the main program. 

Subsequently, whenever execution of the program is interrupted, the debugger 
sets the module that contains the routine in which execution is suspended. 

(For Ada programs, the debugger also sets any module that is related by a 
with-clause or subunit relationship, as explained in Section E.1.14.) This enables 
you to reference the symbols that should be visible at the current PC value (in 
addition to the global symbols). This default mode of operation is called "dynamic 
mode." When setting a module dynamically, the debugger issues a message such 
as the following: 

%DEBUG-I-DYNMODSET, setting module M0D4 

If you try to reference a symbol that is defined in a module that has not been set, 
the debugger warns you that the symbol is not in the RST. You must then use the 
SET MODULE command to set the module containing that symbol explicitly. For 
example: 
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DBG> EXAMINE X 

%DEBUG-E-NOSYMBOL, symbol 'X' is not in the symbol table 

DBG> SET MODULE M0D3 

DBG> EXAMINE X 

MOD3\ROUT2\X: 26 

DBG> 

The SHOW MODULE command lists the modules of your program and identifies 
which modules are set. 

When a module is set, the debugger automatically allocates memory as needed 
by the RST. This can eventually slow down the debugger as more modules are 
set. If performance becomes a problem, you can use the CANCEL MODULE 
command to reduce the number of set modules, thereby automatically releasing 
memory. Or you can disable dynamic mode by entering the command SET MODE 
NODYNAMIC. When dynamic mode is disabled, the debugger does not set 
modules automatically. Use the SHOW MODE command to determine whether 
dynamic mode is enabled or disabled. 

See Appendix E for additional information about module setting specific to Ada 
programs. 

Section 5.4 explains how to set images and modules when debugging shareable 
images. 

5.3 Resolving Symbol Ambiguities 

Symbol ambiguities can occur when a symbol (for example, a variable name X) is 
defined in more than one routine or other program unit. 

In most cases, the debugger resolves symbol ambiguities automatically, using the 
scope and visibility rules of the currently set language and the ordering of routine 
calls on the call stack, as explained in Section 5.3.1. 

However, in some cases the debugger might respond as follows, when you specify 
a symbol that is defined multiple times: 

• It might not be able to determine the particular declaration of the symbol 
that you intended. For example: 

DBG> EXAMINE X 

%DEBUG-W-NOUNIQUE, symbol 'X' is not unique 
DBG> 

• It might reference the declaration that is visible in the current scope, not the 
one you want. 

To resolve such problems, you must specify a scope where the debugger should 
search for a particular declaration of the symbol. In the following example, the 
path name COUNTERXX uniquely specifies a particular declaration of X: 

DBG> EXAMINE COUNTER\X 

COUNTER\X: 14 

DBG> 

The next sections discuss scope concepts and explain how to resolve symbol 
ambiguities. 
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5.3.1 Symbol Lookup Conventions 

This section explains how the debugger searches for symbols, resolving 
most potential symbol ambiguities using the scope and visibility rules of the 
programming language and also its own rules. Section 5.3.2 and Section 5.3.3 
describe supplementary techniques that you can use when necessary. 

You can specify symbols in debugger commands by using either a path name or 
the exact symbol. 

If you use a path name, the debugger looks for the symbol in the scope denoted 
by the path name prefix (see Section 5.3.2). 

If you do not specify a path name prefix, by default, the debugger searches 
the RST as explained in the following paragraphs (you can modify this default 
behavior with the SET SCOPE command, as explained in Section 5.3.3). 

First, the debugger looks for symbols in the PC scope (also known as scope 
0), according to the scope and visibility rules of the currently set language. 

This means that, typically, the debugger first looks within the block or routine 
surrounding the current PC value (where execution is currently suspended). If 
the symbol is not found, the debugger searches the nesting program unit, then 
its nesting unit, and so on. The precise manner, which depends on the language, 
ensures that the correct declaration of a symbol that is defined multiple times is 
chosen. 

However, note that you can reference symbols throughout your program, not 
just those that are visible in the PC scope as defined by the language. This 
is necessary so you can set breakpoints in arbitrary areas, examine arbitrary 
variables, and so on. Therefore, if the symbol is not visible in the PC scope, the 
debugger continues searching as follows. 

After the PC scope, the debugger searches the scope of the calling routine (if 
any), then its caller, and so on. Symbolically, the complete scope search list is 
denoted (0,1,2, ... ,ri), where 0 denotes the PC scope and n is the number of calls 
on the call stack. Within each scope (call frame), the debugger uses the visibility 
rules of the language to locate a symbol. 

This search list, based on the call stack, enables the debugger to differentiate 
symbols that are defined multiple times in a convenient, predictable way. 

If the symbol is still not found, the debugger searches the rest of the RST—that 
is, the other set modules and the global symbol table (GST). At this point the 
debugger does not attempt to resolve any symbol ambiguities. Instead, if more 
than one occurrence of the symbol is found, the debugger issues a message such 
as the following: 

%DEBUG-W-NOUNIQUE, symbol 'V is not unique 

If you have used a SET SCOPE command to modify the default symbol search 
behavior, you can restore the default behavior with the CANCEL SCOPE 
command. 
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5.3.2 Using SHOW SYMBOL and Path Names to Specify Symbols Uniquely 

If the debugger indicates that a symbol reference is "not unique," use the SHOW 
SYMBOL command to obtain all possible path names for that symbol, then 
specify a path name to reference the symbol uniquely. For example: 

DBG> EXAMINE COUNT 

%DEBUG-W-NOUNIQUE, symbol 'COUNT' is not unique 

DBG> SHOW SYMBOL COUNT 
data MOD7\ROUT3\BLOCKl\COUNT 
data MOD4\ROUT2\COUNT 
routine MOD2\ROUTl\ROUT3\COUNT 

DBG> EXAMINE MOD4\ROUT2\COUNT 

M0D4\R0UT2\COUNT: 12 

DBG> 

The command SHOW SYMBOL COUNT lists all declarations of the symbol 
COUNT that exist in the RST. The first two declarations of COUNT are 
variables (data). The last declaration listed is a routine. Each declaration 
is shown with its path name prefix, which indicates the path (search scope) 
the debugger must follow to reach that particular declaration. For example, 
MOD4\ROUT2\COUNT denotes the declaration of the symbol COUNT in 
routine ROUT2 of module MOD4. 

The path name format is as follows. The leftmost element of a path name 
identifies the module containing the symbol. Moving toward the right, the path 
name lists the successively nested routines and blocks that lead to the particular 
declaration of the symbol (which is the rightmost element). 

Although the debugger always displays symbols with their path names, you need 
to use path names in debugger commands only to resolve an ambiguity. 

The debugger looks up line numbers like any other symbols you specify (by 
default, it first looks in the module where execution is suspended). A common 
use of path names is for specifying a line number in an arbitrary module. For 
example: 

DBG> SET BREAK QUEUE_MANAGER\ILINE 26 

Note that the SHOW SYMBOL command identifies global symbols twice, because 
global symbols are included both in the DST and in the GST. For example: 

DBG> SHOW SYMBOL X 

data ALPHA\X ! global X 

data ALPHA\BETA\X ! local X 

data X (global) ! same as ALPHA\X 

DBG> 

In the case of a shareable image, its global symbols are universal symbols, 
and the SHOW SYMBOL command identifies universal symbols twice (see 
Section 5.1.2 and Section 5.4). 

5.3.2.1 Simplifying Path Names 

Path names are often long. You can simplify the process of specifying path names 
in three ways: 

• Abbreviate a path name. 

• Define a brief symbol for a path name. 

• Set a new search scope so you do not have to use a path name. 
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To abbreviate a path name, delete the names of nesting program units starting 
from the left, leaving enough of the path name to specify it uniquely. For 
example, ROUT3\COUNT is a valid abbreviated path name for the routine 
in the first example of Section 5.3.2. 

To define a symbol for a path name, use the DEFINE command. For example: 

DBG> DEFINE INTX = INT_STACK\CHECK\X 
DBG> EXAMINE INTX 

To set a new search scope, use the SET SCOPE command, which is described in 
Section 5.3.3. 

5.3.2.2 Specifying Symbols in Routines on the Call Stack 

You can use a numeric path name to specify the scope associated with a routine 
on the call stack (as identified in a SHOW CALLS display). The path name prefix 
"0\ " denotes the PC scope, the path name prefix "1\ " denotes scope 1 (the scope 
of the caller routine), and so on. 

For example, the following commands display the current values of two distinct 
declarations of Y, which are visible in scope 0 and scope 2, respectively. 

DBG> EXAMINE 0\Y 
DBG> EXAMINE 2\Y 

By default, the EXAMINE Y command signifies EXAMINE 0\Y. 

See also the description of the SET SCOPE/CURRENT command in Section 5.3.3. 
That command enables you to reset the reference for the default scope search list 
relative to the call stack. 

5.3.2.3 Specifying Global Symbols 

To specify a global symbol uniquely, use a backslash (\ ) as a prefix to the symbol. 
For example, the following command displays the value of the global symbol X: 

DBG> EXAMINE \X 

5.3.2.4 Specifying Routine Invocations 

When a routine is called recursively, you might need to distinguish among several 
calls to the same routine, all of which generate new symbols with identical names. 

You can include an invocation number in a path name to indicate a particular 
call to a routine. The number must be a nonnegative integer and must follow the 
name of the rightmost routine in the path name. Zero denotes the most recent 
invocation; 1 denotes the previous invocation, and so on. For example, if PROG 
calls COMPUTE and COMPUTE calls itself recursively, and each call creates a 
new variable SUM, the following command displays the value of SUM for the 
most recent call to COMPUTE: 

DBG> EXAMINE PROG\COMPUTE 0\SUM 

To refer to the variable SUM that was generated in the previous call to 
COMPUTE, you would express the path name with a 1 in place of the 0. 

When you do not include an invocation number, the debugger assumes that the 
reference is to the most recent call to the routine (the default invocation number 
is 0). 

See also the description of the SET SCOPE/CURRENT command in Section 5.3.3. 
That command enables you to reset the reference for the default scope search list 
relative to the call stack. 
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5.3.3 Using SET SCOPE to Specify a Symbol Search Scope 

By default, the debugger looks up symbols that you specify without a path name 
prefix by using the scope search list described in Section 5.3.1. 

The SET SCOPE command enables you to establish a new scope for symbol 
lookup, so that you do not have to use a path name when referencing symbols in 
that scope. 

In the following example, the SET SCOPE command establishes the path name 
MOD4\ROUT2 as the new scope for symbol lookup. Then, references to Y 
without a path name prefix specify the declaration of Y that is visible in the new 
scope. 

DBG> EXAMINE Y 

IDEBUG-E-NOUNIQUE, symbol 'V is not unique 
DBG> SHOW SYMBOL Y 
data MOD7\ROUT3\BL0CK1\Y 
data MOD4\ROUT2\Y 

DBG> SET SCOPE MOD4\ROUT2 
DBG> EXAMINE Y 
MOD4\ROUT2\Y: 12 
DBG> 

After you have entered a SET SCOPE command, the debugger applies the path 
name you specified in the command to all references that are not individually 
qualified with path names. 

You can specify numeric path names with SET SCOPE (see Section 5.3.2.2). For 
example, the following command sets the current scope to be three calls down 
from the PC scope. 

DBG> SET SCOPE 3 

You can also define a scope search list to specify the order in which the debugger 
should search for symbols. For example, the following command causes the 
debugger to look for symbols first in the PC scope (scope 0) and then in the scope 
denoted by routine ROUT2 of module MOD4: 

DBG> SET SCOPE 0, MOD4\ROUT2 

The debugger’s default scope search list is equivalent to entering the following 
command (if it existed): 

DBG> SET SCOPE 0,1,2,3, . . . ,n 

Here the debugger searches successively down the call stack to find a symbol. 

You can use the SET SCOPE/CURRENT command to reset the reference for the 
default scope search list to another routine down the call stack. For example, the 
following command sets the scope search list to be 2,3,4, ... ,n: 

DBG> SET SCOPE/CURRENT 2 

To display the current scope search list for symbol lookup, use the SHOW SCOPE 
command. To restore the default scope search list (see Section 5.3.1), use the 
CANCEL SCOPE command. 
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5.4 Debugging Shareable Images 

By default, your program might be linked with several Digital-supplied shareable 
images (for example, the run-time library image MTHRTL.EXE). This section 
explains how to extend the concepts described in the previous sections when 
debugging user-defined shareable images. 

A shareable image is not intended to be directly executed. A shareable image 
must first be included as input in the linking of an executable image, and then 
the shareable image is loaded at run time when the executable image is run. You 
do not have to install a shareable image to debug it. Instead, you can debug your 
own private copy by assigning a logical name to it. 

See the VMS Linker Utility Manual for detailed information about linking 
shareable images. 

5.4.1 Compiling and Linking Shareable Images for Debugging 

The basic steps in compiling and linking a shareable image for debugging are as 
follows (an example follows the steps): 

1. Compile the source files for the main image and for the shareable image, 
using the /DEBUG qualifier. 

2. Link the shareable image with the /SHAREABLE and /DEBUG command 
qualifiers, declaring any universal symbols for that image using the 
UNIVERSAL linker option. (A universal symbol is a global symbol that 
is defined in a shareable image and referenced in another image.) 

3. Link the shareable image against the main image, specifying the shareable 
image with the /SHAREABLE file qualifier as a linker option. Also specify 
the /DEBUG command qualifier. 

4. Define a logical name to point to the local copy of the shareable image. You 
must specify the device and directory as well as the image name. Otherwise 
the VMS image activator looks for an image of that name in the system 
default shareable image library directory, SYS$SHARE. 

5. Execute the main image to invoke the debugger. The shareable image is 
loaded at run time. 

These steps are illustrated next with a simple example. In the example, 
MAIN.FOR and SUB 1.FOR are the source files for the main image (the 
executable image that you specify with the RUN command); SHR1.FOR and 
SHR2.FOR are the source files for the shareable image to be debugged. 

You compile the source files for each image as described in Section 5.1: 

$ FORTRAN/NOOPT/DEBUG MAIN,SUB1 
$ FORTRAN/NOOPT/DEBUG SHR1,SHR2 

You then use the LINK command to create the shareable image, also specifying 
any universal symbols: 

$ LINK/SHAREABLE/DEBUG SHR1,SHR2,SYS$INPUT:/OPTIONS 
UN I VERS AL=S HR_ROUT |cwz] 

$ 

In the preceding example, 

• The /SHAREABLE command qualifier creates the shareable image SHR1.EXE 
from the object files SHRl.OBJ and SHR2.0BJ. 
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• The /OPTIONS qualifier appended to SYS$INPUT: enables you to specify the 
global symbol SHR_ROUT as a universal symbol interactively. 

• The /DEBUG qualifier builds a DST and a GST for SHR1.EXE and puts them 
in that image. The GST contains the universal symbol SHRJROUT. 

You have now built the shareable image SHR1.EXE in your current default 
directory. Because SHR1.EXE is a shareable image, you do not execute it 
directly with the RUN command. Instead you link SHR1.EXE against the m ain 
(executable) image: 

$ LINK/DEBUG MAIN,SUB1,SYS$INPUT:/OPTION 
SHR1. EXE/SHAREABLE |cwzl 
$ 

In the preceding example, 

• The LINK command creates the executable image MAIN.EXE from 
MAIN.OBJ and SUBl.OBJ. 

• The /DEBUG qualifier builds a DST and a GST for MAIN.EXE and puts them 
in that image. 

• The /SHAREABLE qualifier appended to SHR1.EXE specifies that SHR1.EXE 
is to be linked against MAIN.EXE as a shareable image. 

When you execute the resulting main image, MAIN.EXE, any shareable images 
linked against it are loaded at run time. However, by default the VMS image 
activator looks for shareable images in the system default shareable image 
library directory, SYS$SHARE. Therefore, you must define the logical name 
SHR1 to point to SHR1.EXE in your current default directory. Be sure to specify 
the device and directory: 

$ DEFINE SHR1 SYS$DISK:[]SHR1.EXE 

You can now invoke the debugger to debug both MAIN and SHR1 by entering the 
following command: 

$ RUN MAIN 

5.4.2 Accessing Symbols in Shareable Images 

All the concepts covered in Section 5.1, Section 5.2, and Section 5.3 apply to the 
modules of a single image, namely the main (executable) image. This section 
provides additional information that is specific to debugging shareable images. 

When you link shareable images for debugging as explained in Section 5.4.1, 
the linker builds a DST and a GST for each image. The GST for a shareable 
image contains only universal symbols. To conserve memory, the debugger builds 
an RST for an image only when that image is "set," either dynamically by the 
debugger or when you enter a SET IMAGE command. 

The SHOW IMAGE command identifies all shareable images that are linked with 
your program, shows which images are set, and identifies the current image (see 
Section 5.4.2.2 for a definition of the current image). Only the main image is set 
initially when you invoke the debugger. 

The following sections explain how the debugger sets images dynamically 
during program execution and how you can access symbols in arbitrary images 
independently of execution. 

Refer also to Section 3.6.2.4 for information about setting watchpoints in installed 
writable shareable images. 
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5.4.2.1 Accessing Symbols in the PC Scope (Dynamic Mode) 

By default, dynamic mode is enabled. Therefore, whenever the debugger 
interrupts execution, the debugger sets the image and module where execution is 
suspended, if they are not already set. 

Dynamic mode gives you the following access to symbols automatically: 

• You can reference symbols defined in all set modules in the image where 
execution is suspended. 

• You can reference any universal symbols in the GST for that image. 

By setting other modules in that image with the SET MODULE command, you 
can reference any symbol defined in the image. 

After an image is set, it remains set until you cancel it with the CANCEL 
IMAGE command. If the debugger slows down as more images and modules 
are set, use the CANCEL IMAGE command. You can also enter the SET MODE 
NODYNAMIC command to disable dynamic mode. 

5.4.2.2 Accessing Symbols in Arbitrary Images 

The last image that you or the debugger sets is the current image. The current 
image is the debugging context for symbol lookup. Therefore, when using the 
following commands, you can reference only the symbols that are defined in the 
current image: 

• DEFINE/ADDRESS 

• DEFINE/VALUE 

• DEPOSIT 

• EVALUATE 

• EXAMINE 

• TYPE 

• (SET,CANCEL) BREAK 

• (SET,SHOW,CANCEL) MODULE 

• (SET,CANCEL) TRACE 

• (SET,CANCEL) WATCH 

• SHOW SYMBOL 

However, note that the SHOW BREAK, SHOW TRACE, and SHOW WATCH 
commands identify any breakpoints, tracepoints, or watchpoints that have been 
set in all images. 

To reference a symbol in another image, use the SET IMAGE command to make 
the specified image the current image, then use the SET MODULE command to 
set the module where that symbol is defined (the SET IMAGE command does not 
set any modules). The following example illustrates these concepts. 

The sample program consists of a main image PROG1 and a shareable image 
SHR1. Assume that you have just invoked the debugger and that execution is 
suspended within the main program unit, in image PROG1. Now, suppose you 
want to set a breakpoint on routine ROUT2, which is defined in some module in 
image SHR1. 
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If you try to set a breakpoint on ROUT2, the debugger looks for ROUT2 in the 
current image, PROG1: 

DBG> SET BREAK R0UT2 

%DEBUG-E-NOSYMBOL, symbol 'R0UT2' is not in symbol table 
DBG> 

The SHOW IMAGE command shows that image SHR1 needs to be set: 

DBG> SHOW IMAGE 


image name 


set 

base address 

end address 

*PR0G1 


yes 

00000200 

000009FF 

SHR1 


no 

00001000 

00001FFF 

total images: 2 

DBG> SET IMAGE SHR1 

DBG> SHOW IMAGE 


bytes allocated: 

32856 

image name 


set 

base address 

end address 

PR0G1 


yes 

00000200 

000009FF 

*SHR1 


yes 

00001000 

00001FFF 

total images: 
DBG> 

2 


bytes allocated: 

41948 


SHR1 is now set and is the current image. However, because the SET IMAGE 
command does not set any modules, you must set the module where ROUT2 is 
defined before you can set the breakpoint: 

DBG> SET BREAK R0UT2 

%DEBUG-E-NOSYMBOL, symbol 'R0UT2' is not in symbol table 
DBG> SET MODULE/ALL 
DBG> SET BREAK R0UT2 
DBG> GO 

break at routine R0UT2 

10: SUBROUTINE ROUT2(A,B) 

DBG> 

Now that you have set image SHR1 and all its modules and have reached the 
breakpoint at ROUT2, you can debug using the normal method (for example, step 
through the routine, examine variables, and so on). 

After you have set an image and set modules within that image, the image and 
modules remain set even if you establish a new current image. However, you 
have access to symbols only in the current image at any one time. 

5.4.2.3 Accessing Universal Symbols in Run-Time Libraries and System Images 

The following paragraphs describe how to access a universal symbol (such as 
a routine name) in a run-time library or other shareable image for which no 
symbol-table information was generated. With this information you can, for 
example, use the CALL command to execute a run-time library or system-service 
routine as explained in Section 8.7. 

If no symbol-table information was generated for a shareable image, you cannot 
set the image with the SET IMAGE command. For example, suppose you want to 
set image LIBRTL, which is linked with program EIGHTQUEENS: 

DBG> SHOW IMAGE 


image name 

set 

base address 

end address 

*EIGHTQUEENS 

yes 

00000200 

000009FF 

DBGSSISHR 

no 

00075000 

000783FF 

DEBUG 

no 

00022200 

00074FFF 

LIBRTL 

no 

00000A00 

000199FF 

PASRTL 

no 

00019A00 

000221FF 
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total images: 5 bytes allocated: 108560 

DBG> SET IMAGE LIBRTL 

IDEBUG-I-UNASETIMG, unable to set image LIBRTL because 
it has no symbol table 

To set the image in such cases, use the SET MODULE command with the 
following command syntax: 

SET MODULE SHARE$/'mage-name 

For example: 

DBG> SET MODULE SHARE$LIBRTL 

The debugger creates dummy modules for each shareable image in your program. 
The names of these shareable "image modules" have the prefix "SHARE$". The 
command SHOW MODULE/SHARE identifies these shareable image modules, as 
well as the modules in the current image. 

Once a shareable image module has been set with the SET MODULE command, 
you can access all of its universal symbols. For example, the following command 
lists all of the universal symbols in LIBRTL: 

DBG> SHOW SYMBOL * IN SHARE$LIBRTL 


routine SHARE$LIBRTL\STR$APPEND 
routine SHARE$LIBRTL\STR$DIVIDE 
routine SHARE$LIBRTL\STR$ROUND 


routine SHARE$LIBRTL\LIB$WAIT 
routine SHARE$LIBRTL\LIB$GETDVI 


You can then specify these universal symbols with, for example, the CALL or SET 
BREAK command. 

Setting a shareable image module with the SET MODULE command loads the 
universal symbols for that image into the run-time symbol table so that you can 
reference these symbols from the current image. However, you cannot reference 
other (local or global) symbols in that image from the current image. That is, 
your debugging context remains set to the current image. 


5-16 















__ 6 

Controlling the Display of Source Code 


The term source code refers to statements in a programming language as they 
appear in a source file. Each line of source code is also called a source line. 

This chapter covers the following topics: 

• How the debugger obtains information about source files and source lines. 

• Specifying the location of a source file that has been moved to another 
directory after it was compiled. 

• Displaying source lines by specifying line numbers, code address expressions, 
or search strings. 

• Controlling the display of source code at breakpoints, tracepoints, and 
watchpoints and after a STEP command has been executed. 

• Using the SET MARGINS command to improve the display of source lines 
under certain circumstances. 

The techniques described in this chapter apply to screen mode as well as line 
(noscreen) mode. Any difference in behavior between line mode and screen mode 
is identified in this chapter and in the command dictionary for the commands 
discussed. (Screen mode is described fully in Chapter 7.) 

If your program has been optimized by the compiler, the code that is executing 
as you debug might not always match your source code. See Section 9.1 for 
information about that subject. 

6.1 How the Debugger Obtains Source Code Information 

When a compiler processes source files to generate object modules, it assigns 
a line number to each source line sequentially. For most languages, each 
compilation unit (module) starts with line 1. For others like Ada, each source file, 
which might represent several compilation units, starts with line 1. 

Line numbers appear in a source listing obtained with the /LIST compile- 
command qualifier. They also appear whenever the debugger displays source 
code, either in line mode or screen mode. Moreover, you can specify line numbers 
with several debugger commands (for example, TYPE and SET BREAK). 

The debugger displays source lines only if you have specified the /DEBUG 
command with both the compile command and the LINK command. Under these 
conditions, the symbol information created by the compiler and passed to the 
debug symbol table (DST) includes source-line correlation records. For a given 
module, source-line correlation records contain the full VMS file specification 
of each source file that contributes to that module. In addition, they associate 
source records (symbols, types, and so on) with source files and line numbers in 
the module. 
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6.2 Specifying the Location of Source Files 

The debug symbol table (DST) contains the full VMS file specification of each 
source file when it was compiled. Thus, by default, the debugger expects a source 
file to be in the same directory it was in at compile time. If a source file is moved 
to a different directory after it is compiled, the debugger does not find it and 
displays a warning such as the following when attempting to display source code 
from that file: 

IDEBUG-W-UNAOPNSRC, unable to open source file DISK:[JONES.WORK]PRG.FOR;2 

In such cases, use the SET SOURCE command to direct the debugger to the new 
directory. The command can be applied to all source files for your program or to 
only the source files for specific modules. 

For example, after the following command line is entered, the debugger looks for 
all source files in WORK$:[JONES.PROG3]: 

DBG> SET SOURCE WORKS:[JONES.PR0G3] 

You can specify a directory search list with the SET SOURCE command. 

For example, after the following command line is entered, the debugger 
looks for source files first in the current default directory ([ ]) and then in 
WORK$:[JONES.PROG3]: 

DBG> SET SOURCE [], WORKS:[JONES.PR0G3] 

If you want to apply the SET SOURCE command only to the source files for a 
given module, use the /MODULE=module-name qualifier and specify that module. 
For example, the following command line specifies that the source files for module 
SCREEN_IO are in the directory DISK2:[SMITH.SHARE] (the search of source 
files for other modules is not affected by this command): 

DBG> SET SOURCE/MODULE=SCREEN_IO DISK2:[SMITH.SHARE] 

In summary, the SET SOURCE/MODULE command specifies the location of 
source files for a particular module, whereas the SET SOURCE command 
specifies the location of source files for modules that were not mentioned 
explicitly in SET SOURCE/MODULE commands. 

Use the SHOW SOURCE command to display all source directory search lists 
currently in effect. The command displays the search lists for specific modules (as 
previously established by one or more SET SOURCE/MODULE commands) and 
the search list for all other modules (as previously established by a SET SOURCE 
command). For example: 

DBG> SET SOURCE [PROJA],[PROJB],USERS:[PETER.PROJC] 

DBG> SET SOURCE/MODULE=COBOLTEST [], DISK$2:[PROJD] 

DBG> SHOW SOURCE 

source directory search list for COBOLTEST: 

[] 

DISK$2:[PROJD] 

source directory search list for all other modules: 

[PROJA] 

[PROJB] 

USERS:[PETER.PROJC] 

DBG> 

If no SET SOURCE or SET SOURCE/MODULE command has been entered, the 
SHOW SOURCE command indicates that no search list is currently in effect. 
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Use the CANCEL SOURCE command to cancel the effect of a previous SET 
SOURCE command. Use the CANCEL SOURCE/MODULE command to cancel 
the effect of a previous SET SOURCE/MODULE command (specifying the same 
module name). 

When a source directory search list has been canceled, the debugger again 
expects the source files corresponding to the designated modules to be in the 
same directories they were in at compile time. 

See the description of the SET SOURCE command in the command dictionary for 
additional information about how the debugger locates source files that have been 
moved to another directory after compile time. 

Opening a source file requires the use of an I/O channel, a limited system 
resource. Like the debugger, your program might need to open files. To ensure 
that the debugger does not use all available I/O channels and thus cause the 
program to fail, by default the debugger can keep a maximum of 5 source files 
open at one time. To specify a different limit, use the SET MAX_SOURCE_FILES 
command. For example, the following command line sets the limit to 7 source 
files: 

DBG> SET MAXIMUM_SOURCE_FILES 7 

Note that the value specified limits only the number of source files that can be 
kept open at any one time. If the debugger reaches this limit, it closes a file 
in order to open another one. Note also that setting the limit to a very small 
number can make the debugger’s use of source files inefficient. 

The SHOW MAX_SOURCE_FILES command displays the number of source files 
that the debugger can keep open at one time. 

6.3 Displaying Source Code by Specifying Line Numbers 

The TYPE command enables you to display source lines by specifying compiler- 
assigned line numbers, where each line number designates a line of source 
code. 

For example, the following command displays line 160 and lines 22 to 24 of the 
module being debugged: 

DBG> TYPE 160, 22:24 
module COBOLTEST 

160: START-IT-PARA. 
module COBOLTEST 

22: 02 SC2V2 PIC S99V99 COMP VALUE 22.33. 

23: 02 SC2V2N PIC S99V99 COMP VALUE -22.33. 

24: 02 CPP2 PIC PP99 COMP VALUE 0.0012. 

DBG> 

You can display all the source lines of a module by specifying a range of line 
numbers starting from 1 and ending at a number equal to or greater than the 
largest line number in the module. 

After displaying a source line, you can display the next line in that module by 
entering a TYPE command without a line number—that is, by entering a TYPE 
command and then pressing the Return key. For example: 
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DBG> TYPE 160 
module COBOLTEST 

160: START-IT-PARA. 

DBG> TYPE 
module COBOLTEST 

161: MOVE SCI TO ESO. 

DBG> 

You can then display the next line and successive lines by entering the TYPE 
command repeatedly, in this way reading through your code one line at a time. 

To display source lines in an arbitrary module of your program, specify the 
module name with the line numbers. Use standard path name notation—that is, 
first specify the module name, then a backslash (\ ), and finally the line numbers 
(or the range of fine numbers), without intervening spaces. For example, the 
following command displays line 16 of module TEST: 

DBG> TYPE TEST\16 

If you specify a module name with the TYPE command, the module must be set. 
Use the SHOW MODULE command to determine whether a particular module is 
set. Then use the SET MODULE command, if necessary (see Section 5.2). 

If you do not specify a module name with the TYPE command, the debugger 
displays source lines for the module in which execution is currently suspended, by 
default—that is, the module associated with the PC scope. If you have specified 
another scope with the SET SCOPE command the debugger displays source lines 
in the module associated with the specified scope. 

In screen mode, the output of a TYPE command updates the current source 
display (see Section 7.6.6). 

After displaying source lines at various locations in your program, you can 
redisplay the line at which execution is currently suspended by pressing keypad 
key 5 (KP5). 

6.4 Displaying Source Code by Specifying Code Address 
Expressions 

The EXAMINE/SOURCE command enables you to display the source line 
corresponding to a code address expression. A code address expression denotes 
the address of a machine code instruction and, therefore, must be one of the 
following: 

• A line number associated with one or more instructions 

• A label 

• A routine name 

• The memory address of an instruction 

You cannot specify a variable name with the EXAMINE/SOURCE command, 
because a variable name is associated with data, not with instructions. 

When you use the EXAMINE/SOURCE command, the debugger evaluates the 
address expression to obtain a memory address, determines which compiler- 
assigned line number corresponds to that address, and then displays the source 
line designated by the line number. 
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For example, the following command line displays the source line associated with 
the address (declaration) of routine SWAP: 

DBG> EXAMINE/SOURCE SWAP 
module MAIN 

47: procedure SWAP(X,Y: in out INTEGER) is 

DBG> 

If you specify a line number that is not associated with an instruction, the 
debugger issues a diagnostic message. For example: 

DBG> EXAMINE/SOURCE %LINE 6 

IDEBUG-I-LINEINFO, no line 6, previous line is 5, next line is 8 
%DEBUG-E-NOSYMBOL, symbol '%LINE 6' is not in the symbol table 
DBG> 

When using the EXAMINE/SOURCE command, with a symbolic address 
expression (a line number, label, or routine), you might need to set the module 
in which the entity is defined, unless that module is already set. Use the SHOW 
MODULE command to determine whether a particular module is set. Then use 
the SET MODULE command, if necessary (see Section 5.2). 

The command EXAMINE/SOURCE .%PC displays the source line corresponding 
to the current PC value (the line that is about to be executed). For example: 

DBG> EXAMINE/SOURCE .%PC 
module COBOLTEST 

162: DISPLAY ESO. 

DBG> 

Note the use of the "contents-of" operator (.), which specifies the contents of 
the entity that follows the period. If you do not use the contents-of operator, 
the debugger tries to find a source line for the PC rather than for the address 
currently stored in the PC: 

DBG> EXAMINE/SOURCE %PC 

$DEBUG-W-NOSRCLIN, no source line for address 7FFF005C 
DBG> 

The following example shows the use of a numeric path name (1 \) to display 
the source line at the PC value one level down the call stack (at the call to the 
routine in which execution is suspended): 

DBG> EXAMINE/SOURCE .1\%PC 

In screen mode, the output of an EXAMINE/SOURCE command updates the 
current source display (see Section 7.6.6). 

The debugger uses the EXAMINE/SOURCE command in the following contexts to 
display source code at the current PC value. 

Keypad key 5 (KP5) is bound to the following debugger command sequence: 
EXAMINE/SOURCE .%SOURCE_SCOPE\%PC; EXAMINE/INST .%INST_SCOPE\%PC 

This command sequence displays the source line and the instruction at which 
execution is currently suspended in the current scope. Thus, pressing KP5 
enables you to quickly determine your debugging context. 

The predefined source display SRC is an automatically updated display that 
executes the following built-in command every time the debugger interrupts 
execution and prompts for commands (see Section 7.2.1 and Section C.3.1): 

EXAMINE/SOURCE .ISOURCE SCOPEXIPC 
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6.5 Displaying Source Code by Searching for Strings 

The SEARCH command enables you to display any source lines that contain an 
occurrence of a specified string. 

The syntax of the SEARCH command is as follows: 

SEARCH[/qfua//7/e/{, ... ]] [range] [string] 

The range parameter can be a module name, a range of line numbers, or a 
combination of both. If you do not specify a module name, the debugger uses the 
current scope to find source lines, as with the TYPE command (see Section 6.3). 

By default, the SEARCH command displays the source line that contains the first 
(next) occurrence of a string in a specified range (SEARCH/NEXT). The command 
SEARCH/ALL displays all source lines that contain an occurrence of a string in a 
specified range. For example, the following command line displays the source line 
that contains the first occurrence of the string "pro" in module SCREEN_IO: 

DBG> SEARCH SCREEN_IO pro 

The remaining examples use source lines from one COBOL module, in the current 
scope, to illustrate various aspects of the SEARCH command. 

The following command line displays all source lines within lines 40 to 50 that 
contain an occurrence of the string "D". 

DBG> SEARCH/ALL 40:50 D 
module COBOLTEST 


40: 02 

D2N 

COMP-2 

VALUE 

-234560000000. 

41: 02 

D 

COMP-2 

VALUE 

222222.33. 

42: 02 

DN 

COMP-2 

VALUE 

-222222.333333. 

47: 

02 

DR0 

COMP-2 

VALUE 

0.1. 

48: 

02 

DR 5 

COMP-2 

VALUE 

0.000001. 

49: 

02 

DR10 

COMP-2 

VALUE 

0.00000000001. 

50: 

02 

DR15 

COMP-2 

VALUE 

0.0000000000000001 


DBG> 

After you have found an occurrence of a string in a particular module, you can 
enter the SEARCH command with no parameters to display the source line 
containing the next occurrence of the same string in the same module. This is 
analogous to using the TYPE command without a parameter to display the next 
source line. For example: 

DBG> SEARCH 42:50 D 
module COBOLTEST 

42: 02 DN COMP-2 VALUE -222222.333333. 

DBG> SEARCH 
module COBOLTEST 

47: 02 DR0 COMP-2 VALUE 0.1. 

DBG> 

By default, the debugger searches for a string as specified and does not interpret 
the context surrounding an occurrence of the string (this is the behavior of 
SEARCH/STRING). If you want to locate occurrences of a string that is an 
identifier in your program (for example, a variable name) and exclude other 
occurrences of the string, use the /IDENTIFIER qualifier. The command 
SEARCH/IDENTIFIER displays only those occurrences of the string that are 
bounded on either side by a character that cannot be part of an identifier in the 
current language. 
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The default qualifiers for the SEARCH command are /NEXT and /STRING. If you 
want to establish different default qualifiers, use the SET SEARCH command. 
For example, after the following command is executed, the SEARCH command 
behaves like SEARCH/IDENTIFIER: 

DBG> SET SEARCH IDENTIFIER 

Use the SHOW SEARCH command to display the default qualifiers currently in 
effect for the SEARCH command. For example: 

DBG> SHOW SEARCH 

search settings: search for next occurrence, as an identifier 
DBG> 

6.6 Controlling Source Display After Stepping and at Event Points 

By default, the debugger displays the associated source line when a breakpoint, 
tracepoint, or watchpoint is triggered and upon the completion of a STEP 
command. 

When you enter a STEP command, the debugger displays the source line at which 
execution is suspended after the step. For example: 

DBG> STEP 

stepped to MAIN\%LINE 16 
16: RANGE := 500; 

DBG> 

When a breakpoint or tracepoint is triggered, the debugger displays the source 
line at the breakpoint or tracepoint, respectively. For example: 

DBG> SET BREAK SWAP 
DBG> GO 


break at MAIN\SWAP 

47: procedure SWAP(X,Y: in out INTEGER) is 

DBG> 

When a watchpoint is triggered, the debugger displays the source line 
corresponding to the instruction that caused the watchpoint to be triggered. 

The SET STEP [NO]SOURCE command enables you to control the display of 
source code after a step and at breakpoints, tracepoints, and watchpoints. SET 
STEP SOURCE, the default, enables source display. SET STEP NOSOURCE 
suppresses source display. For example: 

DBG> SET STEP NOSOURCE 
DBG> STEP 

stepped to MAIN\ILINE 16 
DBG> SET BREAK SWAP 
DBG> GO 


break at MAIN\SWAP 
DBG> 

You can selectively override the effect of a SET STEP SOURCE command or 
a SET STEP NOSOURCE command by using the qualifiers /SOURCE and 
/NOSOURCE with the STEP, SET BREAK, SET TRACE, and SET WATCH 
commands. 
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The STEP/SOURCE command overrides the effect of the SET STEP NOSOURCE 
command, but only for the duration of that STEP command (similarly, STEP 
/NOSOURCE overrides the effect of SET STEP SOURCE for the duration of that 
STEP command). For example: 

DBG> SET STEP NOSOURCE 
DBG> STEP/SOURCE 
stepped to MAIN\%LINE 16 
16: RANGE := 500; 

DBG> 

The SET BREAK/SOURCE command overrides the effect of the SET STEP 
NOSOURCE command, but only for the breakpoint set with that SET BREAK 
command (similarly, SET BREAK/NOSOURCE overrides the effect of SET STEP 
SOURCE for the breakpoint set with that SET BREAK command). The same 
conventions apply to the SET TRACE and SET WATCH commands. For example: 

DBG> SET STEP SOURCE 

DBG> SET BREAK/NOSOURCE SWAP 

DBG> GO 


break at MAIN\SWAP 
DBG> 

6.7 Setting Margins for Source Display 

The SET MARGINS command enables you to specify the leftmost and rightmost 
source-line character positions at which to begin and end the display of a source 
line (respectively, the left and right margins). This is useful for controlling the 
display of source code when, for example, the code is deeply indented or long lines 
wrap at the right margin. In such cases, you can set the left margin to eliminate 
indented space in the source display, and you can decrease the right margin 
setting to truncate lines and prevent them from wrapping. 

For example, the following command line sets the left margin to column 20 and 
the right margin to column 35. 

DBG> SET MARGINS 20:35 

Subsequently, only that portion of the source code that is between columns 20 and 
35 is displayed when you enter commands that display source lines (for example, 
TYPE, SEARCH, STEP). Use the SHOW MARGINS command to identify the 
current margin settings for the display of source lines. 

Note that the SET MARGINS command affects only the display of source lines. 

It does not affect the display of other debugger output, as from an EXAMINE 
command. 

The SET MARGINS command is useful mostly in line (noscreen) mode. In screen 
mode, the SET MARGINS command has no effect on the display of source lines 
in a source display, such as the predefined display SRC. 
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Screen mode enables you to see more information more conveniently than the 
default, line-oriented, display mode. In screen mode, you display different types 
of data in separate areas of the screen. You might, for example, display your 
source code in the top left half of the screen, the contents of the VAX registers in 
the top right half, debugger output in the middle, and diagnostic messages at the 
bottom, near your interactive input. 

To enable screen mode, press the PF3 key (or type the SET MODE SCREEN 
command). To return to line-oriented debugging, press GOLD-PF3 (or type the 
SET MODE NOSCREEN command). In screen mode, to re-create the default 
layout of various windows, press BLUE-MINUS (PF4 followed by the MINUS key 
(-)). 

Screen mode output is best displayed on VT100-, VT200-, or VT300-series 
terminals and workstations running VWS. The larger screen of workstations 
is particularly suitable to using a number of displays for different purposes. 

You can use screen mode with VT52 terminals, but they are less suited to the 
formatted screen displays because they do not support the scrolling regions used 
in screen mode. 

This chapter covers the following topics: 

• Screen mode concepts and terminology used throughout the chapter 

• The predefined displays SRC, OUT, PROMPT, INST, and REG, which are 
automatically available when you enter screen mode 

• Scrolling, hiding, deleting, moving, and resizing a display 

• Creating a new display 

• Specifying a display window 

• The different kinds of displays and how to use them 

• Directing various types of debugger output to different displays by assi gnin g 
display attributes 

• A sample display configuration that illustrates a possible use of screen mode 

• Saving the current state of your screen displays 

• Changing your terminal screen’s height and width during a debugging session 
and the effect on display windows 

Many screen mode commands are bound to keypad keys. See Appendix B for 
key definitions. Also, Appendix C contains screen mode information in summary 
reference format. 
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_ Note - 

This chapter provides information common to programs that run in one or 
several processes. See Chapter 10 for additional information specific to 
multiprocess programs. 


7.1 Concepts and Terminology 

A display is a group of text lines. The text might be lines from a source file, 
assembly language instructions, the values contained in registers, your input to 
the debugger, various types of debugger output, or program input and output. 

You view a display through its window, which can occupy any rectangular area 
of the screen. Because a display’s window is typically smaller than the display, 
you can scroll the window up, down, right, and left across the display text to view 
any part of the display. 

Figure 7-1 is an example of screen mode that shows three displays. The name 
of each display (SRC, OUT, and PROMPT) appears at the top left comer of its 
window. It serves both as a tag on the display itself and as a name for future 
reference in commands. 


Figure 7-1 Default Screen Mode Display Configuration 



• Display SRC is a source code display (it is displaying FORTRAN code in the 
example shown in Figure 7-1). SRC’s current window is the upper half of 
the screen. Like other display windows, SRC’s window can be changed to 
accommodate different display layouts. The name of the module whose source 
code is displayed, SQUARES$MAIN, is to the right of the display name. 

• Display OUT, located in a window directly below SRC, shows the output of 
debugger commands. 
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• Display PROMPT, at the bottom of the screen, shows the debugger prompt 
and debugger input. 

Figure 7-1 is the default display configuration that is established when you first 
invoke screen mode. SRC, OUT, and PROMPT are three of the five predefined 
displays that the debugger provides by default when you enter screen mode (see 
Section 7.2). You can create additional displays. 

Every display has a memory buffer, whose size is independent of the window 
size and can be adjusted. Displays that hold source code or assembly language 
instructions enable you to see all of the lines of source code of the associated 
module or all of the instructions of the associated routine, regardless of the size 
of the memory buffer. This is because the necessary information is paged into 
the buffer as needed. For other displays, such as display OUT, the buffer size 
defines how much text the display can hold. If you add more text to the display, 
the oldest text lines are discarded to make room for the new text. 

Conceptually, displays are placed on the screen as on a pasteboard. The display 
that is most recently referenced in a command is put on top of the pasteboard by 
default. Therefore, depending on the window locations, the displays that you have 
referenced recently might overlay or hide other displays (as on a pasteboard). 

The debugger maintains a display list, which is the pasting order of displays. 
Several keypad key definitions use the display list to cycle through the displays 
currently on the pasteboard. 

Every display belongs to a display kind (see Section 7.6). The display kind 
determines what type of information the display can capture and display; for 
example, source code, assembly language instructions, debugger output of various 
types. The display kind also determines how the contents of the display are 
generated. 

The contents of a display are generated in two ways. Some displays are 
automatically updated. Their definition includes a command list that is executed 
whenever the debugger gains control from the program. The output of the 
command list forms the contents of those displays. Display SRC belongs to that 
category: it is automatically updated so that an arrow centered in the window 
shows the source line at which execution is currently suspended. 

Other displays, for example display OUT, derive their contents from commands 
you enter interactively. If you create a display of this general category, you 
must first select it (with the SELECT command) as the target display for one or 
more types of output before anything can be written to it. This is also known as 
assigning one or more display attributes to a display (see Section 7.7). 

The names of any attributes assigned to a display appear to the right of the 
display name, in lowercase letters. In Figure 7-1 SRC has the source and scroll 
attributes (SRC is the current source display and the current scrolling 
display), OUT has the output attribute (it is the current output display), 
and so on. Note that, although SRC is automatically updated by its own built-in 
command, it can also receive the output of certain interactive commands (such as 
EXAMINE/SOURCE) because it has the source attribute. 

The concepts introduced in this section are developed in more detail in the rest of 
this chapter. 
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7.2 Debugger Predefined Displays 

The debugger provides the following predefined displays that you can use to 
capture and display different kinds of data: 

SRC, the predefined source display 
OUT, the predefined output display 
PROMPT, the predefined prompt display 
INST, the predefined instruction display 
REG, the predefined register display 

When you enter screen mode, the debugger puts SRC in the top half of the 
screen, PROMPT in the bottom sixth, and OUT between SRC and PROMPT, as 
illustrated in Figure 7-1. Displays INST and REG are initially removed from the 
screen by default. 

If, after rearranging displays and windows, you want to re-create this default 
configuration, press the keypad-key sequence BLUE-MINUS (PF4 followed by the 
MINUS (-) key). 

The basic features of the predefined displays are described in the next sections. 
As explained in other parts of this chapter, you can change certain characteristics 
of these displays, such as buffer size or display attributes. You can also create 
additional displays similar to the predefined displays. 

7.2.1 Predefined Source Display (SRC) 

_Note_ 

See Chapter 6 for information about how to make source code available 
for display during a debugging session. 


The predefined display SRC (see Figure 7-1) is an automatically updated source 
display. 

You can use SRC to display source code in two basic ways: 

• By default, SRC automatically displays the source code for the module 
in which execution is currently suspended. This enables you to quickly 
determine your current debugging context. 

• In addition, because SRC has the source attribute by default, you can use 
it to display the source code for any part of your program as explained in 
Section 7.2.I.I. 

The name of the module whose source code is displayed is shown at the right 
of the display name, SRC. The numbers displayed at the left of the source code 
are the compiler-generated line numbers, as they might appear in a compiler¬ 
generated listing file. 

As you execute the program under debugger control, SRC is updated 
automatically whenever execution is suspended. The arrow in the leftmost 
column indicates the source line to be executed next. Specifically, execution is 
suspended at the first VAX instruction associated with that source line. Thus, 
the line indicated by the arrow corresponds to the current PC value. The PC 
(program counter) is a VAX register that contains the memory address of the next 
instruction to be executed. 
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If the debugger cannot locate source code for the routine in which execution is 
suspended (because, for example, the routine is a run-time library routine), it 
tries to display source code in the next routine down on the call stack for which 
source code is available. When displaying source code for such a routine, the 
debugger issues the following message: 

%DEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC. 

Displaying source in a caller of the current routine. 

Figure 7-2 illustrates this feature. The source display shows that a call to routine 
TYPE is currently active. TYPE corresponds to a FORTRAN run-time library 
procedure. No source code is available for that routine, so the debugger displays 
the source code of the calling routine. The output of a SHOW CALLS command, 
shown in the output display, identifies the routine where execution is suspended 
and the call sequence leading to that routine. 

In such cases, the arrow in the source window identifies the line to which 
execution returns after the routine call. Depending on the source language and 
coding style, this might be the line that contains the call statement or the next 
line. 


Figure 7-2 Screen Mode Source Display When Source Code Is Not Available 



If your program was optimized during compilation, the source code displayed 
in SRC might not always represent the code that is actually executing. The 
predefined instruction display INST is useful in such cases, because it shows the 
exact VAX instructions that are executing. See Section 7.2.4. 

The built-in command that automatically updates display SRC is EXAMINE 
/SOURCE .%SOURCE_SCOPE\ %PC. The properties of this command are 
described in Section C.3.1 and Section 6.4. 


7-5 



















Using Screen Mode 

7.2 Debugger Predefined Displays 


7.2.1.1 Displaying Source Code in Arbitrary Program Locations 

You can use display SRC to display source code throughout your program, if 
source code is available for display: 

• You can scroll through the entire source display by pressing keypad key KP2 
(scroll down) or KP8 (scroll up) as explained in Section 7.3.1. This enables you 
to view any source line within the module in which execution is suspended. 

• You can display the source code for any routine that is currently on the call 
stack by using the SET SCOPE/CURRENT command (see Section 7.2.1.2). 

• Because SRC has the source attribute, you can display source code throughout 
your program by using the TYPE and EXAMINE/SOURCE commands: 

— To display arbitrary source lines use the TYPE command (see Section 6.3). 

— To display the source line associated with a code location (for example, 
a routine declaration), use the EXAMINE/SOURCE command (see 
Section 6.4). 

When using the TYPE or EXAMINE/SOURCE command, make sure that the 
module in which you want to view source code is set first. Use the SHOW 
MODULE command to determine whether a particular module is set. Then 
use the SET MODULE command, if necessary (see Section 5.2). 

After manipulating the contents of display SRC, you can redisplay the location at 
which execution is currently suspended (the default behavior of SRC) by pressing 
keypad key KP5. 

7.2.1.2 Displaying Source Code for a Routine on the Call Stack 

The command SET SCOPE/CURRENT enables you to display the source code 
for any routine that is currently on the call stack. For example, the following 
command updates display SRC so that it shows the source code for the caller of 
the routine in which execution is currently suspended: 

DBG> SET SCOPE/CURRENT 1 

To reset the default scope for displaying source code, enter the command CANCEL 
SCOPE. The command causes display SRC to show the source code for the routine 
at the top of the call stack, where execution is suspended. 

7.2.2 Predefined Output Display (OUT) 

Figure 7-1 and Figure 7-2 show some typical debugger output in the predefined 
display OUT. 

Display OUT is a general purpose output display. By default, OUT has the output 
attribute and therefore displays any debugger output that is not directed to the 
source display SRC or the instruction display INST. For example, if display INST 
is not displayed or does not have the instruction attribute, any output that would 
otherwise update display INST is shown in display OUT. 

By default, OUT does not display debugger diagnostic messages (these appear 
in the PROMPT display). You can assign attributes to OUT so that it captures 
debugger input and diagnostics as well as normal output (see Section 7.7). 
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7.2.3 Predefined Prompt Display (PROMPT) 

The predefined display PROMPT is the display in which the debugger prompts 
for input. Figure 7-1 and Figure 7-2 show PROMPT in its default location, the 
bottom sixth of the screen. 

By default, PROMPT has the program and error attributes, in addition to the 
prompt attribute. Therefore, by default, the debugger forces program output to 
PROMPT and prints diagnostic messages to that display. 

PROMPT has different properties and restrictions than other displays. This is to 
eliminate possible confusion when manipulating that display: 

• The debugger always keeps PROMPT on top of the display pasteboard so it 
cannot be hidden by another display. You cannot hide PROMPT (with the 
DISPLAY/HIDE command), or remove PROMPT from the pasteboard (with 
the DISPLAY/REMOVE command), or permanently delete PROMPT (with the 
CANCEL DISPLAY command). 

• PROMPT can have the scroll attribute, so that it can be made the default 
target display for the MOVE and EXPAND commands. But you cannot scroll 
PROMPT. 

• You can move PROMPT anywhere on the screen, expand it to fill the full 
screen height, and contract it down to two lines. But PROMPT must always 
occupy the full width of the screen. Therefore, you cannot move, expand, or 
contract PROMPT horizontally. 

The debugger alerts you if you try to move or expand a display such that it is 
hidden by PROMPT. 

7.2.4 Predefined Instruction Display (INST) 

-Note_ 

By default, the predefined instruction display INST is not shown on the 
screen and does not have the instruction attribute (see Section 7.2.4.1 and 
Section 7.2.4.2). 


Display INST is an automatically updated instruction display. It shows the 
decoded VAX assembly-language instruction stream of your program. This is the 
exact code that is executing, including the effects of any compiler optimization. 
An example is shown in Figure 7-3. 

This type of display is useful when debugging code that has been optimized. In 
such cases some of the code being executed might not match the source code that 
is shown in a source display. See Section 9.1 for information about the effects of 
optimization. 

You can use INST in two basic ways: 

• By default, INST automatically displays the decoded instructions for the 
routine in which execution is currently suspended. This enables you to 
quickly determine your current debugging context. 
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Figure 7-3 Screen Mode Instruction Display 
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• In addition, if INST has the instruction attribute, you can use it to display 
the decoded instructions for any part of your program as explained in 
Section 7.2.4.2. 

The name of the routine whose instructions are displayed is shown at the right of 
the display name, INST. The numbers displayed at the left of the instructions are 
the compiler-generated source line numbers. 

As you execute the program under debugger control, INST is updated 
automatically whenever execution is suspended. The arrow in the leftmost 
column points to the instruction at which execution is suspended. This is the 
instruction that will be executed next and whose address is the current PC value. 

The built-in command that automatically updates display INST is EXAMINE 
/INSTRUCTION .%INST_SCOPE\%PC. The properties of this command are 
described in Section C.3.4 and Section 4.3.1. 

7.2.4.1 Displaying the Instruction Display 

By default, display INST is marked as removed (see Section 7.3.2) from the 
display pasteboard and is not visible. To show display INST, use one of the 
following methods: 

• Press keypad key KP7 to place displays SRC and INST side by side. This 
enables you to readily compare the source code and the decoded instruction 
stream. 

• Press the keypad key sequence PF1 KP7 to place displays INST and REG 
side by side. 

• Enter the DISPLAY INST command to place INST in its default or most 
recently defined location (see Section 7.3.2). 
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7.2.4.2 Displaying Instructions in Arbitrary Program Locations 

You can use display INST to display decoded instructions throughout your 
program: 

• You can scroll through the entire instruction display by pressing keypad 
key KP2 (scroll down) or KP8 (scroll up) as explained in Section 7.3.1. This 
enables you to view any instruction within the routine in which execution is 
suspended. 

• You can display the instruction stream for any routine that is currently on the 
call stack by using the SET SCOPE/CURRENT command (see Section 7.2.4.3). 

• If INST has the instruction attribute, you can display the instructions 
for any code location throughout your program by using the EXAMINE 
/INSTRUCTION command: 

1. To assign INST the instruction attribute, use the command SELECT 
/INSTRUCTION INST (see Section 7.6.2 and Section 7.7). Note that the 
instruction attribute is automatically assigned to INST when you display 
it by pressing either keypad key KP7 or the key sequence PF1 KP7. 

2. To display the instructions associated with a code location (for example, 
a routine declaration), use the EXAMINE/INSTRUCTION command (see 
Section 4.3.1). 

If no display has the instruction attribute, the output of an EXAMINE 
/INSTRUCTION command is directed at display OUT. 

After manipulating the contents of display INST, you can redisplay the location at 
which execution is currently suspended (the default behavior of INST) by pressing 
keypad key KP5. 

7.2.4.3 Displaying Instructions for a Routine on the Call Stack 

The command SET SCOPE/CURRENT enables you to display the instructions 
for any routine that is currently on the call stack. For example, the following 
command updates display INST so that it shows the instructions for the caller of 
the routine in which execution is currently suspended: 

DBG> SET SCOPE/CURRENT 1 

To reset the default scope for displaying instructions, enter the CANCEL SCOPE 
command. The command causes display INST to show the instructions for the 
routine at the top of the call stack, where execution is suspended. 

7.2.5 Predefined Register Display (REG) 

The predefined register display REG shows the current values, in hexadecimal 
format, of the VAX general registers (RO to Rll, AP, FP, SP, PC), the four 
condition code bits (C, V, Z, and N) of the processor status longword (PSL), and 
as many of the top stack values as can be displayed through the window (see 
Figure 7-4). 
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Figure 7-4 Screen Mode Register Display 
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The register values displayed are for the routine in which execution is currently 
suspended. The values are updated whenever the debugger takes control. Any 
changed values are highlighted. 

REG is initially marked as removed (see Section 7.3.2) from the display 
pasteboard and is not visible. You must use the DISPLAY command (or the 
keypad key sequence GOLD KP7) to show the REG display. Pressing GOLD KP7 
enables you to place REG next to display INST. 

If the register window is made larger, the debugger fills the remaining space with 
information contained in the user call stack. 

REG does not display the current values of the VAX vector registers. To display 
data contained in vector registers or vector control registers in screen mode, use a 
DO display. (See Section 7.6.1.) 

7.3 Manipulating Existing Displays 

This section explains how to perform the following functions: 

• Use the SELECT and SCROLL commands to scroll a display. 

• Use the DISPLAY command to show, hide, or remove a display; the CANCEL 
DISPLAY command to permanently delete a display; and the SHOW 
DISPLAY command to identify the displays that currently exist and their 
order in the display list. 

• Use the MOVE command to move a display across the screen. 

• Use the EXPAND command to expand or contract a display. 

Note also that Section 7.5 and Section 7.6 discuss more advanced techniques for 
modifying existing displays with the DISPLAY command—how to change the 
display window and the type of information displayed. 
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7.3.1 Scrolling a Display 

A display usually has more lines of text (and possibly longer lines) than can be 
seen through its window. The SCROLL command enables you to view text that is 
hidden beyond a window’s border. You can scroll through all displays except for 
the PROMPT display. 

The easiest way to scroll displays is with keypad keys, as described later in this 
section. First, use of the relevant commands is explained. 

You can specify a display explicitly with the SCROLL command. Typically, 
however, you first use the SELECT/SCROLL command to select the current 
scrolling display. This display then has the scroll attribute and is the default 
display for the SCROLL command. You then use the SCROLL command with 
no parameter to scroll that display up or down by a specified number of lines, or 
to the right or left by a specified number of columns. The direction and distance 
scrolled are specified with the command qualifiers (/UP:n, /RIGHT:ra, and so on). 

In the following example, the SELECT command selects display OUT as the 
current scrolling display (/SCROLL can be omitted because it is the default 
qualifier); the SCROLL command then scrolls OUT to reveal text 18 lines down: 

DBG> SELECT OUT 
DBG> SCROLL/DOWN:18 

Several useful SELECT and SCROLL command lines are assigned to keypad keys 
(see Appendix B for the keypad diagram): 

• Pressing key 3 assigns the scroll attribute to the next display in the display 
list after the current scrolling display. So, to select a display as the current 
scrolling display, press key 3 repeatedly until the word "scroll" appears on 
the top line of that display. 

• Press key KP8, KP2, KP6, or KP4 to scroll up, down, right, or left, 
respectively. The amount of scroll depends on which key state you use 
(DEFAULT, GOLD, or BLUE). 

7.3.2 Showing, Hiding, Removing, and Canceling a Display 

The DISPLAY command is the most versatile command for creating and 
manipulating displays. In its simplest form, the command puts an existing 
display on top of the pasteboard, where it appears through its current window. 

For example, the following command shows the display INST through its current 
window: 

DBG> DISPLAY INST 

Pressing keypad key KP9, which is bound to the DISPLAY %NEXTDISP 
command, enables you to achieve this effect conveniently. The built-in function 
%NEXTDISP signifies the next display in the display list (Appendix D identifies 
all screen-related built-in functions). Each time you press KP9, the next display 
in the list is put on top of the pasteboard, in its current window. 

Note that, by default, the top line of display OUT (which identifies the display) 
coincides with the bottom line of display SRC. If SRC is on top of the pasteboard, 
its bottom line hides the top line of OUT (keep this in mind when using the 
DISPLAY command and associated keypad keys to put various displays on top of 
the pasteboard). 

To hide a display at the bottom of the pasteboard, use the DISPLAY/HIDE 
command. This command changes the order of that display in the display list. 
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To remove a display from the pasteboard so that it is no longer seen (yet is not 
permanently deleted), use the DISPLAY/REMOVE command. To put a removed 
display back on the pasteboard, use the DISPLAY command. 

To delete a display permanently, use the CANCEL DISPLAY command. To 
re-create the display, use the DISPLAY command as described in Section 7.4. 

Note that you cannot hide, remove, or delete the PROMPT display. 

To identify the displays that currently exist, use the SHOW DISPLAY command. 
They are listed according to their order on the display list. The display that is on 
top of the pasteboard is listed last. 

See the command dictionary for information about the various options provided 
by the DISPLAY command qualifiers. Note also that the DISPLAY command 
accepts optional parameters that enable you to modify other characteristics 
of existing displays, namely the display window and the type of information 
displayed. The techniques are discussed in Section 7.5 and Section 7.6. 

7.3.3 Moving a Display Across the Screen 

Use the MOVE command to move a display across the screen. The qualifiers 
/UP:n, /DOWN :n, /RIGHT:n, and /LEFT:n specify the direction and the number of 
lines or columns by which to move the display. If you do not specify a display, the 
current scrolling display is moved. 

The easiest way to move a display is by using keypad keys: 

• Press key KP3 repeatedly as needed to select the current scrolling display. 

• Put the keypad in the MOVE state, then use keys KP8, KP2, KP4, or KP6 to 
move the display up, down, left, or right, respectively (see Appendix B). 

7.3.4 Expanding or Contracting a Display 

Use the EXPAND command to expand or contract a display. The qualifiers /UP:n, 
/DOWN:n, /RIGHTS, and /LEFT:ra specify the direction and the number of lines 
or columns by which to expand or contract the display (to contract a display, 
specify negative integer values with these qualifiers). If you do not specify a 
display, the current scrolling display is expanded or contracted. 

The easiest way to expand or contract a display is by using keypad keys. 

• Press key KP3 repeatedly as needed to select the current scrolling display. 

• Put the keypad in the EXPAND or CONTRACT state, then use keys KP8, 
KP2, KP4, or KP6 to expand or contract the display vertically or horizontally 
(see Appendix B). 

Note that the PROMPT display cannot be contracted (or expanded) horizontally. 
Also, it cannot be contracted vertically to less than two lines. 

7.4 Creating a New Display 

To create a new screen display, use the DISPLAY command. The basic syntax is 
as follows: 

DISPLAY display-name [AT window-specification] [display-kind] 
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The display name can be any name that is not already used to name a display 
(use the SHOW DISPLAY command to identify all existing displays). When you 
create a new display, it is placed on top of the pasteboard, on top of any existing 
displays (except for the predefined PROMPT display, which cannot be hidden). 
The display name appears at the top left comer of the display window. 

Section 7.5 explains the options for specifying windows. If you do not provide a 
window specification, the display is positioned in the upper or lower half of the 
screen, alternating between these locations as you create new displays. 


Section 7.6 explains the options for specifying display kinds. If you do hot specify 
a display kind, an output display is created. 


For example, the following command creates a new output display named OUT2 
The window associated with OUT2 is either the top or bottom half of the screen. 

DBG> DISPLAY 0UT2 

The following command creates a new "DO" display named EXAM_XY that is 
located in the right third quarter (RQ3) of the screen. This display shows the 
current value of variables X and Y and is updated whenever the debugger gains 
control from the program. 


DBG> DISPLAY EXAM_XY AT RQ3 DO (EXAMINE X,Y) 

See the command dictionary for information about the various options provided 
by the DISPLAY command qualifiers. 

7.5 Specifying a Display Window 

Display windows can occupy any rectangular portion of the screen. 

You can specify a display window when you create a display with the DISPLAY 
command. You can also change the window currently associated with a display 
by specifying a new window with the DISPLAY command. When specifying a 
window, you have the following options: 

• Specify a window in terms of lines and columns. 

• Use the name of a predefined window, such as HI. 

• Use the name of a window definition previously established with the SET 
WINDOW command. 

Each of these techniques is described in the next sections. When specifying 
windows, keep in mind that the PROMPT display always remains on top of the 
display pasteboard and, therefore, occludes any part of another display that 
shares the same region of the screen. 

Display windows, regardless of how specified, are dynamic. This means that, if 
you use a SET TERMINAL command to change the screen height or width, the 
window associated with a display expands or contracts in proportion to the new 
screen height or width. 

7.5.1 Specifying a Window in Terms of Lines and Columns 

The general form of a window specification is {start-line,line-count[,start- 
column,column-count]). For example, the following command creates the output 
display CALLS and specifies that its window be 7 lines deep starting at line 10, 
and 30 columns wide starting at column 50: 

DBG> DISPLAY CALLS AT (10,7,50,30) 
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If you do not specify start-column or column-count, the window occupies the full 
width of the screen. 

7.5.2 Predefined Windows 

The debugger provides many predefined windows. These have short symbolic 
names that you can use in the DISPLAY command instead of having to specify 
lines and columns. For example, the following command creates the output 
display ZIP and specifies that its window be RH1 (the top right half of the 
screen). 

DBG> DISPLAY ZIP AT RH1 

The SHOW WINDOW command identifies all predefined window definitions, as 
well as those you create with the SET WINDOW command. 

7.5.3 Creating a New Window Definition 

Although the predefined windows should be adequate for most situations, you 
can also create a new window definition with the SET WINDOW command. 

This command, which has the following form, associates a window name with a 
window specification: 

SET WINDOW window-name AT (start-line,line-count[, start-col,col-counf\) 

After creating a window definition, you can simply use its name (like that of 
a predefined window) in a DISPLAY command. In the following example, the 
window definition MIDDLE is established. That definition is then used to display 
OUT through the window MIDDLE. 

DBG> SET WINDOW MIDDLE AT (9,4,30,20) 

DBG> DISPLAY OUT AT MIDDLE 

To identify all current window definitions, use the SHOW WINDOW command. 
To delete a window definition, use the CANCEL WINDOW command. 

7.6 Specifying the Display Kind 

Every display has a display kind. The display kind determines the type of 
information a display contains and how that information is generated. 

Typically, you specify a display kind when you use the DISPLAY command to 
create a new display (if you do not specify a display kind, an output display is 
created). You can also use the DISPLAY command to change the display kind 
of an existing display. The keywords and associated parameters with which you 
specify a display kind are listed below. Each of these options is explained in the 
sections that follow (refer also to the displays illustrated in Section 7.2). 

DO (command-list) 

INSTRUCTION 
INSTRUCTION ( command) 

OUTPUT 

REGISTER 

SOURCE 

SOURCE (command) 

The contents of a register display are generated and updated automatically 
by the debugger. The contents of other kinds of displays are generated by 
commands, and these display kinds fall into two general groups. 
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A display that belongs to one of the following display kinds has its contents 
updated automatically according to the command or command list you supply 
when defining that display: 

DO 0 command-list) 

INSTRUCTION ( command ) 

SOURCE (command) 

The command list specified is executed each time the debugger gains control from 
your program, provided the display is not marked as removed. The output of 
the commands forms the new contents of the display. If the display is marked 
as removed, the debugger does not execute the command list until you view that 
display (marking that display as unremoved). 

A display that belongs to one of the following display kinds derives its contents 
from commands that you enter interactively: 

INSTRUCTION 

OUTPUT 

SOURCE 

To direct debugger output to a specific display in this group, you must first select 
it with the SELECT command. The technique is explained in the next sections 
and, in further detail, in Section 7.7. After a display is selected for a certain type 
of output, the output from your commands forms the contents of the display. 

The default size of the memory buffer associated with any newly created display 
is 64 lines. For source and instruction displays, the size of the buffer only 
affects performance. In the case of a source display, source files are paged in as 
necessary as you scroll through the module. In the case of an instruction display, 
the instructions are decoded from the image as necessary as you scroll through 
the routine. 

For output and DO displays, the buffer size defines how many lines of text the 
display holds. If you add more text to the display, the oldest lines are discarded 
to make room for the new text. You can use the /SIZE qualifier on the DISPLAY 
command to change the buffer size. 

7.6.1 DO (Command!; ■ ■ • ]) Display Kind 

A DO display is an automatically updated display. The commands in the 
command list are executed in the order listed each time the debugger gains 
control from your program. Their output forms the content of the display, erasing 
any previous content. 

For example, the following command creates the DO display CALLS at window 
Q3. Each time the debugger gains control from the program, the SHOW CALLS 
command is executed and the output is displayed in CALLS, replacing any 
previous contents. 

DBG> DISPLAY CALLS AT Q3 DO (SHOW CALLS) 

The following command creates a DO display named V2_DISP that shows the 
contents of elements 4 to 7 of the VAX vector register V2 (using FORTRAN array 
syntax). The display is automatically updated whenever the debugger gains 
control from the program: 

DBG> DISPLAY V2_DISP AT RQ2 DO (EXAMINE %V2(4:7)) 
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7.6.2 INSTRUCTION Display Kind 

An instruction display shows the output of an EXAMINE/INSTRUCTION 
command within the assembly-language instruction stream of a routine. Because 
the instructions displayed are decoded from the image being debugged and show 
the exact code that is executing, this kind of display is particularly useful in 
helping you debug optimized code (see Section 9.1). 

In the display, one line is devoted to each instruction. Source line numbers 
corresponding to the instructions are displayed in the left column. The instruction 
at the location being examined is centered in the display and is marked by an 
arrow in the left column. 

Before anything can be written to an instruction display, you must select it as the 
current instruction display with the SELECT/INSTRUCTION command. 

In the following example, the DISPLAY command creates the instruction display 
INST2 at RH1. The SELECT/INSTRUCTION command then selects INST2 as 
the current instruction display. When the EXAMINE/INSTRUCTION X command 
is executed, window RH1 fills with the instruction stream surrounding the 
location denoted by X. The arrow points to the instruction at location X, which is 
centered in the display. 

DBG> DISPLAY INST2 AT RH1 INSTRUCTION 
DBG> SELECT/INSTRUCTION INST2 
DBG> EXAMINE/INSTRUCTION X 

Each subsequent EXAMINE/INSTRUCTION command updates the display. 

7.6.3 INSTRUCTION (Command) Display Kind 

This is an instruction display that is automatically updated with the output 
of the command specified. That command, which must be an EXAMINE 
/INSTRUCTION command, is executed each time the debugger gains control 
from your program. 

For example, the following command creates the instruction display INST3 at 
window RS45. Each time the debugger gains control, the built-in command 
EXAMINE/INSTRUCTION ,%INST_SCOPE\ %PC is executed, updating the 
display. 

DBG> DISPLAY INST3 AT RS45 INSTRUCT (EX/INST .%INST_SCOPE\%PC) 

This command creates a display that functions like the predefined display INST. 
The built-in EXAMINE/INSTRUCTION command displays the instruction at the 
current PC value in the current scope (see Section C.3.4). 

If an automatically updated instruction display is selected as the current 
instruction display, it is updated like a simple instruction display by an 
interactive EXAMINE/INSTRUCTION command (in addition to being updated by 
its built-in command). 

7.6.4 OUTPUT Display Kind 

An output display shows any debugger output that is not directed to another 
display. New output is appended to the previous contents of the display. 

Before anything can be written to an output display, it must be selected as 
the current output display with the SELECT/OUTPUT command, or as the 
current error display with the SELECT/ERROR command, or as the current 
input display with the SELECT/INPUT command. See Section 7.7 for more 
information about using the SELECT command with output displays. 
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In the following example, the DISPLAY command creates the output display 
OUT2 at window T2 (the display kind OUTPUT could have been omitted from 
tjus example, because it is the default kind). The SELECT/OUTPUT command 
then selects OUT2 as the current output display. These two commands create a 
display that functions like the predefined display OUT. 

DBG> DISPLAY OOT2 AT T2 OUTPUT 
DBG> SELECT/OUTPUT OUT2 

OUT2 now collects any debugger output that is not directed to another display. 
For example: 

• The output of a SHOW CALLS command goes to OUT2. 

If no instruction display has been selected as the current instruction display 
the output of an EXAMINE/INSTRUCTION command goes to OUT2. 

• By default, debugger diagnostic messages are directed to the PROMPT 
display. They can be directed to OUT2 with the SELECT/ERROR command. 

7.6.5 REGISTER Display Kind 

A register display is an automatically updated display that shows the current 
values, in hexadecimal format, of the VAX general registers (RO to Rll, AP, FP, 
SP, and PC), the four condition code bits (C,V, Z, and N) of the processor status 
longword (PSL), and as many of the top call stack values as can be displayed in 
the window (see Figure 7-4). 

The register values displayed are for the routine in which execution is currently 
suspended. The values are updated whenever the debugger takes control. Any 
changed values are highlighted. 

A register display does not display the current values of the VAX vector registers. 
To display data contained in vector registers or vector control registers in screen 
mode, use a DO display. (See Section 7.6.1.) 

7.6.6 SOURCE Display Kind 

A source display shows the output of a TYPE or EXAMINE/SOURCE command 
within the source code of a module, if that source code is available. Source line 
numbers are displayed in the left column. The source line that is the output of 
the command is centered in the display and is marked by an arrow in the left 
column. If a range of lines is specified with the TYPE command, the lines are 
centered in the display, but no arrow is shown. 

Before anything can be written to a source display, you must select it as the 
current source display with the SELECT/SOURCE command. 

In the following example, the DISPLAY command creates the source display 
SRC2 at Q2. The SELECT/SOURCE command then selects SRC2 as the current 
source display When the TYPE 34 command is executed, window RH1 fills with 
the source code surrounding line 34 of the module being debugged. The arrow 
points to line 34, which is centered in the display. 

DBG> DISPLAY SRC2 AT Q2 SOURCE 
DBG> SELECT/SOURCE SRC2 
DBG> TYPE 34 

Each subsequent TYPE or EXAMINE/SOURCE command updates the display. 
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7.6.7 


SOURCE (Command) Display Kind 

This is a source display that is automatically updated with the outputof the 
command specified. That command, which must be an EXAMINE/SOURCE or 
TYPE command, is executed each time the debugger gains control from your 


program. 

For example, the following command creates a source display SR C3 at window 
RS45. Each time the debugger gains control, the built-in command EXAMINE 
/SOURCE ,%SOURCE_SCOPE\ %PC is executed, updating the display. 

DBG> DISPLAY SRC3 AT RS45 SOURCE (EX/SOURCE .!SOURCE_SCOPE\%PC) 

This command creates a display that functions like the predefined display SRC. 
The built-in EXAMINE/SOURCE command displays the source line for the 
current PC value in the current scope (see Section C.3.1). 


If an automatically updated source display is selected as the current source 
display, it is updated like a simple source display by an interactive EXAMINE 
/SOURCE or TYPE command (in addition to being updated by its built-in 
command). 


7.6.8 PROGRAM Display Kind 

The PROMPT display belongs to the special display kind "program." Note that 
PROMPT is the only display of that kind. You cannot specify that display kind in 
a DISPLAY command. 


To avoid possible confusion, the PROMPT display has several restrictions (see 
Section 7.2.3). 


7.7 Assigning Display Attributes 

In screen mode, the output from commands you enter interactively is directed 
to various displays according to the type of output and the display attributes 
assigned to these displays. For example, debugger diagnostic messages go to the 
display that has the error attribute (the current error display). By assigning 
one or more attributes to a display, you can mix or isolate different kinds of 
information. 

The attributes have the following names: 

error 

input 

instruction 

output 

program 

prompt 

scroll 

source 

When a display is assigned an attribute, the name of that attribute appears 
in lowercase letters on the top border of its window, to the right of the display 
name Note that the scroll attribute does not affect debugger output but is used 
to control the default display for the SCROLL, MOVE, and EXPAND commands. 
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By default, attributes are assigned to the predefined displays as follows: 

• SRC has the source and scroll attributes. 

• OUT has the output attribute. 

• PROMPT has the prompt, program, and error attributes. 

To assign an attribute to a display, use the SELECT command with the qualifier 
of the same name as the attribute. In the following example, the DISPLAY 
command creates the output display ZIP. The SELECT/OUTPUT command 
then selects ZIP as the current output display—the display that has the output 
attribute. After this command is executed, the word "output" disappears from 
the top border of the predefined output display OUT and appears instead on 

display ZIP, and all debugger output formerly directed to OUT is now directed to 
ZIP. 

DBG> DISPLAY ZIP OUTPUT 
DBG> SELECT/OUTPUT ZIP 

Specific attributes can be assigned only to certain display kinds. The following 
list identifies each of the SELECT command qualifiers, its effect, and the display 
kinds to which you can assign that attribute. 

SELECT " ~ -- 

Qualifier Description 

Selects the specified display as the current error display. Directs 
any subsequent debugger diagnostic message to that display. It 
must be either an output display or the PROMPT display. If no 
display is specified, selects the PROMPT display as the current 
error display. 

Selects the specified display as the current input display. Echoes 
any subsequent debugger input in that display. It must be an 
output display. If no display is specified, unselects the current 
input display: debugger input is not echoed to any display. 

Selects the specified display as the current instruction display. 
Directs the output of any subsequent EXAMINE/INSTRUCTION 
command to that display. It must be an instruction display. 
Keypad key sequence BLUE-COMMA selects the next instruction 
display in the display list as the current instruction display. If no 
display is specified, unselects the current instruction display: no 
display has the instruction attribute. 

Selects the specified display as the current output display. Directs 
any subsequent debugger output to that display, except where a 
particular type of output is being directed to another display (such 
as diagnostic messages going to the current error display). The 
specified display must be either an output display or the PROMPT 
display. Keypad key sequence GOLD KP3 selects the next output 
display in the display list as the current output display. If no 
display is specified, selects the PROMPT display as the current 
output display. 

Selects the specified display as the current program display. 

Tries to force any subsequent program input or output to that 
display. Currently, only the PROMPT display can be specified. 

If no display is specified, unselects the current program display: 
program output is no longer forced to the PROMPT display. 


/ERROR 


/INPUT 


/INSTRUCTION 


/OUTPUT 


/PROGRAM 
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SELECT 

Qualifier 

Description 

/PROMPT 

Selects the specified display as the current prompt display, where 
the debugger prompts for input. Currently, only the PROMPT 
display can be specified. You cannot unselect the PROMPT 
display. 

/SCROLL 

Selects the specified display as the current scrolling display. 

Makes that display the default display for any subsequent 
SCROLL, MOVE, or EXPAND command. You can specify any 
display (however, note that the PROMPT display cannot be 
scrolled). The /SCROLL qualifier is the default if you do not 
specify a qualifier with the SELECT command. Key KP3 selects 
as the current scrolling display the next display in the display 
list after the current scrolling display. If no display is specified, 
unselects the current scrolling display: no display has the scroll 
attribute. 

/SOURCE 

Selects the specified display as the current source display. Directs 
the output of any subsequent TYPE or EXAMINE/SOURCE 
command to that display. It must be a source display. Keypad 
key sequence BLUE-KP3 selects the next source display in the 
display list as the current source display. If no display is specified, 
unselects the current source display: no display has the source 
attribute. 


Subject to the restrictions listed, a display can have several attributes. In the 
preceding example, ZIP was selected as the current output display. In the next 
example, ZIP is further selected as the current input, error, and scrolling display. 
After these commands are executed, debugger input, output, and diagnostics 
are logged in ZIP in the proper sequence as they occur, and ZIP is the current 
scrolling display. 

DBG> SELECT/INPUT/ERROR/SCROLL ZIP 

To identify the displays currently selected for each of the display attributes, use 
the SHOW SELECT command. 

If you use the SELECT command with a particular qualifier but without 
specifying a display name, the effect is typically to deassign that attribute (to 
"unselect" the display that had the attribute). The exact effect depends on the 
attribute, as described in the preceding list. 

7.8 A Sample Display Configuration 

How to best use screen mode depends on your personal style and on what type 
of bug you are looking for. You might be satisfied to simply use the predefined 
displays. On the other hand, especially if you have access to a larger screen, 
you might want to create additional displays for various purposes. The following 
example might give you some ideas. 

Assume you are debugging in a high-level language and are interested in tracing 
the execution of your program through several routine calls. 

First set up the default screen configuration—that is, SRC in HI, OUT in 
S45, and PROMPT in S6 (the keypad key sequence BLUE-MINUS gives this 
configuration). SRC shows the source code of the module in which execution is 
suspended. 
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The next command creates a source display named SRC2 in RH1 that shows the 
PC value at scope 1 (one level down the call stack, at the call to the routine in 
which execution is suspended): 

DBG> DISPLAY SRC2 AT RH1 SOURCE (EXAMINE/SOURCE .1\%PC) 

Thus the left half of your screen shows the currently executing routine, whereas 
the right half shows the caller of that routine. 

The next command creates a DO display named CALLS at S4 that executes the 
SHOW CALLS command each time the debugger gains control from the program: 

DBG> DISPLAY CALLS AT S4 DO (SHOW CALLS) 

Because the top half of OUT is now hidden by CALLS, make OUT’s window 
smaller: 

DBG> DISPLAY OUT AT S5 

You can create a similar display configuration with instruction displays instead of 
source displays. 

7.9 Saving Displays and the Screen State 

The SAVE command enables you to make a "snapshot" of an existing display and 
save that copy as a new display. This is useful if, for example, you later want to 
refer to the current contents of an automatically updated display (such as a DO 
display). 

In the following example, the SAVE command saves the current contents of 
display CALLS into display CALLS4, which is created by the command: 

DBG> SAVE CALLS AS CALLS4 

The new display is removed from the pasteboard. So, to view its contents use the 
DISPLAY command: 

DBG> DISPLAY CALLS4 

The EXTRACT command has two uses. First, it enables you to save the contents 
of a display in a text file. For example, the following command extracts the 
contents of display CALLS, appending the resulting text to the file COB34.TXT: 

DBG> EXTRACT/APPEND CALLS COB34 

Second, the EXTRACT/SCREENJ^AYOUT command enables you to create 
a command procedure that can later be invoked during a debugging session 
to re-create the previous state of the screen. In the following example, the 
EXTRACT/SCREENJLAYOUT command creates a command procedure with the 
default specification SYS$DISK:[]DBGSCREEN.COM. The file contains all the 
commands needed to re-create the current state of the screen. 

DBG> EXTRACT/SCREENJLAYOUT 

DBG> QDBGSCREEN 

Note that you cannot save the PROMPT display as another display, or extract it 
into a file. 
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7.10 Changing the Screen Height and Width 

During a debugging session, you might want to change the height or width of 
your terminal screen. One reason might be to accommodate long lines that would 
wrap if displayed across 80 columns. Or, if you are using a workstation, you 
might want to reformat your debugger window relative to other windows. 

To change the screen height or width, use the SET TERMINAL command. 

The general effect of the command is the same whether you are at a VT-series 
terminal or at a workstation. 

In this example, assume you are using a workstation in its default emulated 
VTlOO-screen mode, with a screen size of 24 lines by 80 columns. You have 
invoked the debugger and are using it in screen mode. You now want to 
take advantage of the larger screen. The following command increases the 
screen height and width of the debugger window to 35 lines and 110 columns 
respectively: 

DBG> SET TERMINAL/PAGE:35/WIDTH:110 

By default, all displays are dynamic . A dynamic display automatically adjusts 
its window dimensions in proportion when a SET TERMINAL command 
changes the screen height or width. This means that, when using the SET 
TERMINAL command, you preserve the relative positions of your displays. The 
/[NO]DYNAMIC qualifier on the DISPLAY command enables you to control 
whether or not a display is dynamic. If a display is not dynamic, it does not 
change its window coordinates after you enter a SET TERMINAL command (you 
can then use the DISPLAY, MOVE, or EXPAND commands, or various keypad 
key combinations, to move or resize a display). 

To see the current terminal width and height being used by the debugger, use the 
SHOW TERMINAL command. 

Note that the debugger’s SET TERMINAL command does not affect the terminal 
screen size at DCL level. When you exit the debugger, the original screen size is 
maintained. 
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This chapter describes the following debugger convenience features not described 
elsewhere in this manual: 

• Using debugger command procedures 

• Using an initialization file for a debugging session 

• Logging a debugging session into a file 

• Defining symbols to represent commands, address expressions, or values 

• Assigning debugger commands to function keys 

• Using control structures to enter commands 

• Calling arbitrary routines linked with your program 

8.1 Using Debugger Command Procedures 

A debugger command procedure is a sequence of commands contained in a file. 
You can direct the debugger to execute a command procedure to re-create a 
debugging session, to continue a previous session, or to avoid typing the same 
debugger commands many times during a debugging session. You can pass 
parameters to command procedures. 

As with DCL command procedures, you execute a debugger command procedure 
by preceding its file specification with an at sign (@). The @ is the execute 
procedure command. 

Debugger command procedures are especially useful when you regularly perform 
a number of standard setup debugger commands, as specified in a debugger 
initialization file (see Section 8.2). You can also use a debugger log file as a 
command procedure (see Section 8.3). 

8.1.1 Basic Conventions 

The following is a sample debugger command procedure named BREAK7.COM: 

I ***** Debugger Command Procedure BREAK7.COM ***** 

SET BREAK/AFTER:3 ILINE 120 DO (EXAMINE K,N,J,X(K); GO) 

SET BREAK/AFTER:3 %LINE 160 DO (EXAMINE K,N,J,X(K),S; GO) 

SET BREAK %LINE 90 

When you execute this command procedure with the execute procedure (@) 
command, the commands listed in the procedure are executed in the order they 
appear. 

The rules entering commands in command procedures are listed in Section 1 of 
the command dictionary. 

You can pass parameters to a command procedure. See Section 8.1.2 for 
conventions on passing parameters. 
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You can enter the @ command like any other debugger command—that is, directly 
from the terminal, from within another command procedure, from within a DO 
clause in a command such as SET BREAK, or from within a DO clause in a 
screen display definition. 

If you do not supply a full file specification with the @ command, the debugger 
assumes SYS$DISK:[]DEBUG.COM as the default file specification for command 
procedures. For example, you would enter the following command line to execute 
command procedure BREAK7.COM, located in your current default directory: 

DBG> 0BREAK7 

The SET ATSIGN command enables you to change any or all fields of the default 
file specification, SYS$DISK:[]DEBUG.COM. The command SHOW ATSIGN 
identifies the default file specification for command procedures. 

By default, commands read from a command procedure are not echoed. If you 
enter the SET OUTPUT VERIFY command, all commands read from a command 
procedure are echoed on the current output device, as specified by DBG$OUTPUT 
(the default output device is SYS$OUTPUT). Use the SHOW OUTPUT command 
to determine whether commands read from a command procedure are echoed or 
not. 

If the execution of a command in a command procedure results in a diagnostic 
of severity "warning" or greater, the command is aborted, but execution of the 
command procedure continues at the next command line. 

8.1.2 Passing Parameters to Command Procedures 

As with DCL command procedures, you can pass parameters to debugger 
command procedures. However, the technique is different in several respects. 

Subject to the conventions described here, you can pass as many parameters as 
you want to a debugger command procedure. The parameters can be address 
expressions, commands, or value expressions in the current language. You must 
surround command strings in quotation marks ("), and you must separate 
parameters by commas (,). 

A debugger command procedure to which you pass parameters must contain a 
DECLARE command line that binds each actual (passed) parameter to a formal 
parameter (a symbol) declared within the command procedure. 

The DECLARE command is valid only within a command procedure. Its format 
is as follows: 

DECLARE p-name:p-kind[, p-name:p-kind[, ... ]] 

Each p-name:p-kind pair associates a formal parameter (p-name) with a 
parameter kind ( p-kind ). The valid p-kind keywords are as follows: 

ADDRESS Causes the actual parameter to be interpreted as an address expression. 

COMMAND Causes the actual parameter to be interpreted as a command. 

VALUE Causes the actual parameter to be interpreted as a value expression in 

the current language. 

The following example illustrates what happens when a parameter is passed to 
a command procedure. The command DECLARE KADDRESS, within command 
procedure EXAM.COM, declares the formal parameter K. The actual parameter 
passed to EXAM.COM is interpreted as an address expression. The command 
EXAMINE K displays the value of that address expression. The command SET 
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OUTPUT VERIFY causes the commands to echo when they are read by the 
debugger. 

; ***** Debugger Command Procedure EXAM.COM ***** 

SET OUTPUT VERIFY 
DECLARE K:ADDRESS 
EXAMINE K 

The next command line executes EXAM.COM, passing the actual parameter 
ARR4. Within EXAM.COM, ARR4 is interpreted as an address expression (an 
array variable, in this case). 

DBG> 0EXAM ARR4 

%DEBUG-I-VERIFYIC, entering command procedure EXAM 
DECLARE K:ADDRESS 
EXAMINE K 
PROG_8\ARR4 

(1): 18 

( 2 ): 1 

(3) : 0 

(4) : 1 

%DEBUG-I-VERIFYIC, exiting command procedure EXAM 
DBG> 

Each p-name:p-kind pair specified by a DECLARE command binds one parameter. 
So, for instance, if you want to pass five parameters to a command procedure, you 
need five corresponding p-name:p-kind pairs. The pairs are always processed in 
the order in which you specify them. 

For example, the next command procedure, EXAM_GO.COM accepts two 
parameters, an address expression (L) and a command string (M). The address 
expression is then examined and the command is executed: 

i ***** Debugger Command Procedure EXAM_GO.COM ***** 

DECLARE L:ADDRESS, M:COMMAND 
EXAMINE L; M 

The following example shows how you could execute EXAM_GO.COM, passing a 
variable X to be examined and a command @DUMP.COM to be executed: 

DBG> @EXAM_GO X, "gDUMP" 

The %PARCNT built-in symbol, which can be used only within a command 
procedure, enables you to pass a variable number of parameters to a command 
procedure. The value of %PARCNT is the number of actual parameters passed to 
the command procedure. 

The %PARCNT built-in symbol is illustrated in the following example. The 
command procedure, VAR.DBG, contains the following lines: 

I ***** Debugger Command Procedure VAR.DBG ***** 

SET OUTPUT VERIFY 

! Display the number of parameters passed: 

EVALUATE IPARCNT 

! Loop as needed to bind all passed parameters and obtain their values: 

FOR I = 1 TO IPARCNT DO (DECLARE X:VALUE; EVALUATE X) 

The following command line executes VAR.DBG, passing the parameters 12, 37, 
and 45: 
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DBG> 0VAR.DBG 12,37,45 

%DEBUG-I-VERIFYIC, entering command procedure VAR.DBG 
! Display the number of parameters passed: 

EVALUATE %PARCNT 
3 

! Loop as needed to bind all passed parameters 
! and get their values: 

FOR I = 1 TO IPARCNT DO (DECLARE X:VALUE; EVALUATE X) 

12 

37 

45 

%DEBUG-I-VERIFYIC, exiting command procedure VAR.DBG 
DBG> 

When VAR.DBG is executed, %PARCNT has the value 3. Therefore, the FOR 
loop within VAR.DBG is repeated 3 times. The FOR loop causes the DECLARE 
command to bind each of the three actual parameters (starting with 12) to a new 
declaration of X. Each actual parameter is interpreted as a value expression in 
the current language, and the EVALUATE X command displays that value. 

8.2 Using a Debugger Initialization File 

A debugger initialization file is a command procedure, assigned the logical 
name DBG$INIT, that the debugger automatically executes at debugger startup. 
Every time you invoke the debugger, the commands contained in the file are 
automatically executed. 

An initialization file contains any command lines you might always enter at 
the start of a debugging session to either tailor your debugging environment or 
control the execution of your program in a predetermined way from run to run. 

For example, you might have a file DEBUG__START4.COM containing the 
following commands: 

i ***** Debugger Initialization File DEBUG_START4.COM ***** 

! Log debugging session into default log file (SYS$DISK:[JDEBUG.LOG) 

SET OUTPUT LOG 

i 

! Echo commands as they are read from command procedures: 

SET OUTPUT VERIFY 

i 

! if source files are not in current default directory, use [SMITH.SHARE] 

SET SOURCE [],[SMITH.SHARE] 

i 

! Invoke screen mode: 

SET MODE SCREEN 

j 

! Define the symbol SB as the SET BREAK command: 

DEFINE/COMMAND SB = "SET BREAK" 

i 

! Assign the SHOW MODULE * command to keypad key 7: 

DEFINE/KEY/TERMINATE KP7 "SHOW MODULE *" 

To make this file a debugger initialization file, use the DCL command DEFINE. 
For example: 

$ DEFINE DBG$INIT WORK:[JONES.DBGCOMFILES]DEBUG_START4.COM 
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8.3 Logging a Debugging Session into a File 

A debugger log file maintains a history of a debugging session. During the 
debugging session, each command entered and the resulting debugger output are 
stored in the file. 

The following is an example of a debugger log file. 

SHOW OUTPUT 

Inoverify, terminal, noscreen log, logging to DSK2:[JONES.P71 DEBUG.LOG; 1 

SET STEP NOSOURCE 

SET TRACE %LINE 30 

SET BREAK %LINE 60 

SHOW TRACE 

Itracepoint at PROG4ULINE 30 
GO 

!trace at PROG4\%LINE 30 
Ibreak at PROG4\ILINE 60 


The DBG> prompt is not recorded, and the debugger output is commented out 
with exclamation points so the file can be used as a debugger command procedure 
without modification. Thus, if a lengthy debugging session is interrupted, you 
can execute the log file as you would any other debugger command procedure. 
Executing the log file restores the debugging session to the point at which it was 
previously terminated. 

To create a debugger log file, use the SET OUTPUT LOG command. By default, 
the debugger writes the log to SYS$DISK:[ JDEBUG.LOG. To name a debugger 
log file, use the SET LOG command. You can override any field of the default file 
specification. For example, after you enter the following commands, the debugger 
logs the session to the file [JONES.WORK2JMONITOR.LOG: 

DBG> SET LOG [JONES.WORK2]MONITOR 
DBG> SET OUTPUT LOG 

You might want to enter the SET OUTPUT LOG command in your debugger 
initialization file (see Section 8.2). 

The SHOW LOG command reports whether the debugger is writing to a log file 
and identifies the current log file. The SHOW OUTPUT command identifies all 
current output options. 

If you are debugging in screen mode, the SET OUTPUT SCREEN_LOG command 
enables you to log the screen contents as the screen is updated. To use this 
command, you must already be logging your debugging session—that is, the SET 
OUTPUT SCREENJLOG command is valid only after you have entered the SET 
OUTPUT LOG command. Note that using SET OUTPUT SCREEN.LOG is not 
desirable for a long debugging session, because storing screen information in 
this manner results in a big log file. For other techniques on saving screen-mode 
information, see also the descriptions of the SAVE and EXTRACT commands in 
Chapter 7 and in the command dictionary. 

If you plan to use a log file as a command procedure, you should first enter the 
SET OUTPUT VERIFY command so that debugger commands are echoed as they 
are read. 
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8.4 Defining Symbols for Commands, Address Expressions, and 
Values 

The DEFINE command enables you to create a symbol for a lengthy or often- 
repeated command sequence or address expression and to store the value of a 
language expression in a symbol. 

You specify the kind of symbol you want to define by the command qualifier you 
use with the DEFINE command (/COMMAND, /ADDRESS, or /VALUE). The 
default qualifier is /ADDRESS. If you plan to enter several DEFINE commands 
with the same qualifier, you can first use the SET DEFINE command to establish 
a new default qualifier (for example, SET DEFINE COMMAND makes the 
DEFINE command behave like DEFINE/COMMAND). The SHOW DEFINE 
command identifies the default qualifier currently in effect. 

Use the SHOW SYMBOL/DEFINED command to identify symbols you have 
defined with the DEFINE command. Note that the SHOW SYMBOL command 
without the /DEFINED qualifier identifies only the symbols that are defined in 
your program, such as the names of routines and variables. 

Use the DELETE command to DELETE symbol definitions created with the 
DEFINE command. 

When defining a symbol within a command procedure, use the /LOCAL qualifier 
to confine the symbol definition to that command procedure. 

8.4.1 Defining Symbols for Commands 

Use the DEFINE/COMMAND command to equate one or more commands 
(actually, strings) to a shorter symbol. The basic syntax is illustrated in the 
following example. 

DBG> DEFINE/COMMAND SB = "SET BREAK" 

DBG> SB PARSER 

In the example, the DEFINE/COMMAND command equates the symbol SB 
to the string SET BREAK (note the use of the quotation marks to delimit the 
command string). When the command line SB PARSER is executed, the debugger 
substitutes the string SET BREAK for the symbol SB and then executes the SET 
BREAK command. 

In the following example, the DEFINE/COMMAND command equates the symbol 
BT to the st ring consisting of the SHOW BREAK command followed by the 
SHOW TRACE command(use semicolons to separate multiple command strings): 

DBG> DEFINE/COMMAND BT = "SHOW BREAK;SHOW TRACE" 

The SHOW SYMBOL/DEFINED command identifies the symbol BT as follows: 

DBG> SHOW SYM/DEFINED BT 
defined BT 

bound to: "SHOW BREAK;SHOW TRACE" 
was defined /command 

DBG> 

To define complex commands, you might need to use command procedures with 
parameters (see Section 8.1.2 for information about passing parameters to 
command procedures). For example: 

DBG> DEFINE/COMMAND DUMP = "@DUMP_PR0G2.COM" 
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8.4.2 Defining Symbols for Address Expressions 

Use the DEFINE/ADDRESS command to equate an address expression to a 
symbol. Although /ADDRESS is the default qualifier for the DEFINE command, 
it is used in the following examples for emphasis. 

In the following example, the symbol B1 is equated to the address of line 378; the 
SET BREAK B1 command then sets a breakpoint on line 378. 

DBG> DEFINE/ADDRESS B1 = %LINE 378 
DBG> SET BREAK B1 

The DEFINE/ADDRESS command is useful when you need to specify a lo ng path 
name repeatedly to reference the name of a variable or routine that is defined 
multiple times. In the next example, the symbol UX is equated to the path name 
SCREEN_IO\UPDATE\X; the abbreviated command line EXAMINE UX can 
then be used to obtain the value of X in routine UPDATE of module SCREEN_IO. 

DBG> DEFINE UX = SCREEN_IO\UPDATE\X 
DBG> EXAMINE UX 

8.4.3 Defining Symbols for Values 

Use the DEFINE/VALUE command to equate the current value of a language 
expression to a symbol (the current value is the value at the time the DEFINE 
/VALUE command was entered). 

The following example illustrates how the DEFINE/VALUE command can be used 
to count the number of calls to a routine. 

DBG> DEFINE/VALUE COUNT = 0 

DBG> SET TRACE/SILENT ROUT DO (DEFINE/VALUE COUNT = COUNT + 1) 

DBG> GO 


DBG> EVALUATE COUNT 
14 

DBG> 

In the example, the first DEFINE/VALUE command initializes the value of the 
symbol COUNT to 0. The SET TRACE command sets a silent tracepoint on 
routine ROUT and (through the DO clause) increments the value of COUNT by 1 
every time ROUT is called. After execution is resumed and eventually suspended, 
the EVALUATE command obtains the current value of COUNT (the number of 
times that ROUT was called). 

8.5 Assigning Commands to Function Keys 

To facilitate entering commonly used commands, the function keys on the keypad 
have predefined debugger functions that are established when you invoke the 
debugger. These predefined functions are identified in detail in Appendix B. You 
can modify the functions of the keypad keys to suit your individual needs. If 
you have a VT200- or VT300-series terminal or a workstation, you can also bind 
commands to the additional function keys on the LK201 keyboard. 

The debugger commands DEFINE/KEY, SHOW KEY, and DELETE/KEY enable 
you to assign, identify, and delete key definitions, respectively. Before you can 
use this feature, keypad mode must be enabled with the SET MODE KEYPAD 
command (keypad mode is enabled by default). Keypad mode also enables you to 
use the predefined functions of the keypad keys. 
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If you want to use the keypad keys to enter numbers rather than debugger 
commands, enter the SET MODE NOKEYPAD command. 

8.5.1 Basic Conventions 

The debugger DEFINE/KEY command, which is similar to the DCL DEFINE 
/KEY command, enables you to assign a string to a function key. In the following 
example, the DEFINE/KEY command defines keypad key 7 to enter and execute 
the SHOW MODULE * command: 

DBG> DEFINE/KEY/TERMINATE KP7 "SHOW MODULE *" 

%DEBUG-I-DEFKEY, DEFAULT key KP7 has been defined 
DBG> 

The /TERMINATE qualifier indicates that pressing key 7 executes the command. 
You do not have to press Return after pressing key 7. 

KP7 is the key name that you must use with the commands DEFINE/KEY, 
SHOW KEY, and DELETE/KEY. The valid key names that you can use with 
these commands are listed in the command dictionary for VT52 and VTlOO-series 
terminals and for LK201 keyboards (see the command descriptions). 

The same function key can be assigned any number of definitions as long 
as each definition is associated with a different state. The predefined states 
(DEFAULT, GOLD, BLUE, and so on) are identified in Appendix B. In the 
preceding example, the informational message indicates that key 7 has been 
defined for the DEFAULT state (which is the default key state). 

You can enter key definitions in a debugger initialization file (see Section 8.2) so 
that these definitions are available whenever you invoke the debugger. 

To display a key definition in the current state, enter the SHOW KEY command. 
For example: 

DBG> SHOW KEY KP7 
DEFAULT keypad definitions: 

KP7 = "SHOW MODULE *" (echo,terminate,nolock) 

DBG> 

To display a key definition in a state other than the current state, specify that 
state with the /STATE qualifier when entering the SHOW KEY command. To see 
all key definitions in the current state, enter the SHOW KEY/ALL command. 

To delete a key definition, use the DELETE/KEY command. To delete a key 
definition in a state other than the current state, specify that state with the 
/STATE qualifier. For example: 

DBG> DELETE/KEY/STATE=GOLD KP7 

%DEBUG-I-DELKEY, GOLD key KP7 has been deleted 

DBG> 

8.5.2 Advanced Techniques 

This section illustrates more advanced techniques for defining keys, particularly 
techniques related to the use of state keys. 

The following command line assigns the unterminated command string "SET 
BREAK %LINE" to keypad key 9, for the BLUE state. 

DBG> DEFINE/KEY/IF_STATE=BLUE KP9 "SET BREAK %LINE" 
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The predefined DEFAULT key state is established by default. The predefined 
BLUE key state is established by pressing the PF4 key. You would enter the 
command line assigned in the preceding example (SET BREAK %LINE ... ) by 
pressing key PF4, pressing KP9, entering a line number, and then pressing the 
Return key to terminate and process the command line. 

The SET KEY command enables you to change the default state for key 
definitions. For example, after entering the SET KEY/STATE=BLUE command, 
you would not need to press PF4 to enter the command line in the previous 
example. Also, the SHOW KEY command would show key definitions in the 
BLUE state, by default, and the DELETE/KEY command would delete key 
definitions in the BLUE state by default. 

You can create additional key states. For example: 

DBG> SET KEY/STATE=DEFAULT 

DBG> DEFINE/KEY/SET_STATE=RED/LOCK_STATE F12 "" 

In this example, the SET KEY command establishes DEFAULT as the current 
state. The DEFINE/KEY command makes key F12 (LK201 keyboard) a state key. 
As a result, pressing F12 while in the DEFAULT state causes the current state to 
become RED. The key definition is not terminated and has no other effect (a null 
string is assigned to F12). After pressing F12, you can enter "RED" commands 
by pressing keys that have definitions associated with the RED state. 

8.6 Using Control Structures to Enter Commands 

The FOR, IF, REPEAT, and WHILE commands enable you to create looping and 
conditional constructs for entering debugger commands. The associated command 
EXITLOOP is used to exit a FOR, REPEAT, or WHILE loop. 

See Section 4.1.5 and Section 9.3.2.2 for information about evaluating language 
expressions. 

8.6.1 FOR Command 

The FOR command executes a sequence of commands while incrementing a 
variable a specified number of times. It has the following format: 

FOR name=expression1 TO expression2 [BY expression3\ DO(command[; ... ]) 

For example, the following command line sets up a loop that initializes the first 
10 elements of an array to zero: 

DBG> FOR I = 1 TO 10 DO (DEPOSIT A(I) = 0) 

8.6.2 IF Command 

The IF command executes a sequence of commands if a language expression 
(Boolean expression) is evaluated as true. It has the following format: 

IF boolean-expression THEN {command[\ ... ]) [ELSE (command[\ ...])] 

The following FORTRAN example sets up a condition that issues the command 
EXAMINE X2 if XI is not equal to —9.9, and issues the command EXAMINE Y1 
otherwise: 

DBG> IF XI .NE. -9.9 THEN (EXAMINE X2) ELSE (EXAMINE Yl) 

The following Pascal example combines a FOR loop and a condition test. The 
STEP command is issued if XI is not equal to —9.9. The test is made four times: 

DBG> FOR COUNT = 1 TO 4 DO (IF XI <> -9.9 THEN (STEP)) 
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8.6.3 REPEAT Command 

The REPEAT command executes a sequence of commands a specified number of 
times. It has the following format: 

REPEAT language-expression DO ( command [; ... ]) 

For example, the following command line sets up a loop that issues a sequence of 
two commands (EXAMINE Y then STEP) 10 times: 

DBG> REPEAT 10 DO (EXAMINE Y; STEP) 

8.6.4 WHILE Command 

The WHILE command executes a sequence of commands while the language 
expression (Boolean expression) you have specified evaluates as true. It has the 
following format: 

WHILE boolean-expression DO ( command [; ... ]) 

The following Pascal example sets up a loop that tests XI and X2 repetitively and 
issues the two commands EXAMINE X2 and STEP if X2 is less than XI: 

DBG> WHILE X2 < XI DO (EX X2;STEP) 

8.6.5 EXITLOOP Command 

The EXITLOOP command exits one or more enclosing FOR, REPEAT, or WHILE 
loops. It has the following format: 

EXITLOOP [n] 

The integer n specifies the number of nested loops to exit from. 

The following Pascal example sets up an endless loop that issues a STEP 
command with each iteration. After each step, the value of X is tested. If X is 
greater than 3, the EXITLOOP command terminates the loop. 

DBG> WHILE TRUE DO (STEP; IF X > 3 THEN EXITLOOP) 

8.7 Calling Routines Independently of Program Execution 

The CALL command enables you to execute a routine independently of the 
normal execution of your program. It is one of the four debugger commands that 
can be used to execute your program (the others are GO, STEP, and EXIT). 

The CALL command executes a routine whether or not your program actually 
includes a call to that routine, so long as the routine was linked with your 
program. Thus you can use the CALL command to execute routines for any 
purpose (for example, to debug a routine out of the context of program execution, 
invoke a run-time library procedure, execute a routine that dumps debugging 
information, and so on). 

You can debug unrelated routines by linking them with a dummy main program 
that has a transfer address, and then using the CALL command to execute them. 

The following example shows how you could use the CALL command to display 
some process statistics without having to include the necessary code in your 
program. The example consists of calls to run-time library routines that initialize 
a timer (LIB$INIT_TIMER) and display the elapsed time and various statistics 
(LIB$SHOW_TIMER). (Note that the presence of the debugger affects the timings 
and counts.) 
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DBG> SET MODULE SHARE$LIBRTL O 
DBG> CALL LIB$INIT_TIMER © 
value returned is 1 © 

DBG> [ enter various debugger commands ] 


DBG> CALL LIB$SHOW_TIMER © 

ELAPSED: 0 00:00:21.65 CPU: 0:14:00.21 BUFIO: 16 DIRIO: 0 FAULTS: 3 
value returned is 1 
DBG> 

The comments that follow refer to the callouts in the previous example: 

O Routines LIB$INIT_TIMER and LIB$SHOW_TIMER are in the shareable 
image LIBRTL. This image must be set by setting its "module" because 
only its universal symbols are accessible during a debugging session (see 
Section 5.4.2.3). 

© This CALL command executes routine LIB$INIT_TIMER. 

© The "value returned" message indicates the value returned in register RO 
after the CALL command has been executed. 

By VMS convention, after a called routine has executed, register RO contains 
the function return value (if the routine is a function) or the procedure 
completion status (if the routine is a procedure that returns a status value). 
If a called procedure does not return a status value or function value, the 
value in RO might be meaningless, and the "value returned" message can be 
ignored. 

© This CALL command executes routine LIB$SHOW_TIMER. 

The following example shows how to call LIB$SHOW_VM (also in LIBRTL) to 
display memory statistics. (Again, note that the presence of the debugger affects 
the counts): 

DBG> SET MODULE SHARE$LIBRTL 
DBG> CALL LIB$SHOW_VM 

1785 calls to LIB$GET_VM, 284 calls to LIB$FREE_VM, 

122216 bytes still allocated value returned is 1 
DBG> 

You can pass parameters to routines with the CALL command. See the 
description of the CALL command in the command dictionary for details 
and examples. 
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Debugging Special Cases 


This chapter presents debugging techniques for special cases that are not covered 
elsewhere in this manual: 

• Optimized code 

• Screen-oriented programs 

• Multilanguage programs 

• Exceptions and condition handlers 

• Exit handlers 

• AST-driven programs 

9.1 Debugging Optimized Code 

By default, many compilers optimize the code they produce so that the program 
executes faster. The net result is that the code that is executing as you debug 
might not match the source code displayed in a screen-mode source display 
(see Section 7.2.1) or in a source listing file. For example, some optimization 
techniques eliminate variables so that you no longer have access to them while 
debugging. 

To avoid the problems of debugging optimized code, many compilers allow you 
to specify the /NOOPTIMIZE (or equivalent) command qualifier at compile 
time. Specifying this qualifier inhibits most compiler optimization, thereby 
reducing discrepancies between the source code and executable code caused by 
optimization. 

If this option is not available to you, read this section. It describes the techniques 
for debugging optimized code and gives some typical examples of optimized code 
to illustrate the potential causes of confusion. 

When debugging optimized code, use a screen-mode instruction display, such 
as the predefined display INST, to show the decoded VAX assembly-language 
instruction stream of your program (see Section 7.2.4). An instruction display 
shows the exact code that is executing. 

In screen mode, pressing keypad key KP7 places the SRC and INST displays side 
by side for easy comparison. Alternatively, you can inspect a compiler-generated 
machine code listing. 

In addition, to execute the program at the instruction level and examine 
instructions, use the techniques described in Section 4.3. 

Using these methods, you should be able to determine what is happening at the 
executable code level and thereby resolve the discrepancy between source display 
and program behavior. 
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9.1.1 Eliminated Variables 

A compiler might optimize code by eliminating variables, either permanently or 
temporarily at various points during execution. If you try to examine a variable 
X that no longer is accessible because of optimization, the debugger might display 
one of the following messages: 

%DEBUG-W-UNALLOCATED, entity X was not allocated in memory 
(was optimized away) 

%DEBUG-W-NOVALATPC, entity X does not have a value at the 
current PC (was optimized away) 

The following Pascal example shows how this could happen: 

PROGRAM DOC(OUTPUT); 

VAR 

X,Y: INTEGER; 

BEGIN 

X := 5; 

Y := 2; 

WRITELN(X*Y); 

END. 

If you compile this program with the /NOOPTIMIZE (or equivalent) qualifier, you 
obtain the following (normal) behavior when debugging: 

$ PASCAL/DEBUG/NOOPTIMIZE DOC 
$ LINK/DEBUG DOC 
$ RUN DOC 


DBG> STEP 

stepped to DOC\%LINE 5 
5: X := 5; 

DBG> STEP 

stepped to DOCMLINE 6 
6: Y := 2; 

DBG> STEP 

stepped to DOCMLINE 7 

7: WRITELN(X*Y); 

DBG> EXAMINE X,Y 
DOC\X: 5 _ 

D0C\Y: 2 

DBG> 

If you compile the program with the /OPTIMIZE (or equivalent) qualifier, because 
the values of X and Y are not changed after the initial assignment, the compiler 
calculates X*Y, stores that value (10), and does not allocate storage for X or Y. 
Therefore, after you invoke the debugger, a STEP command takes you directly to 
line 7 rather than line 5. Moreover, you cannot examine X or Y: 

$ PASCAL/DEBUG/OPTIMIZE DOC 
$ LINK/DEBUG DOC 
$ RUN DOC 


DBG> EXAMINE X,Y 

%DEBUG-W-NOVALATPC, entity X does not have a value at the 
current PC (was optimized away) 

DBG> STEP 

stepped to D0C\%LINE 7 

7: WRITELN(X*Y); 

DBG> 
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To see what values are being used in your optimized program, use the command 
EXAMINE/OPERAND .%PC to display the machine code at the current PC value, 
including the values and symbolization of all of the operands. For example, the 
following lines show the optimized code when the PC value is at the WRITELN 
statement: 

DBG> STEP 

stepped to D0C\%LINE 7 

7: WRITELN(X*Y); 

DBG> EXAMINE/OPERAND .%PC 
DOCULINE 7: PUSHL S A #10 

DBG> 

In contrast, the following lines show the unoptimized code at the WRITELN 
statement: 

DBG> STEP 

stepped to D0C\%LINE 7 

7: WRITELN(X*Y); 

DBG> EXAMINE/OPERAND .%PC 
DOCULINE 7: MOVL S A #10,B A -4 (FP) 

B A -4(FP) 2146279292 contains 62914576 

DBG> 

9.1.2 Changes in Coding Order 

Several methods of optimizing consist of performing operations in a sequence 
different from the sequence specified in the source code. Sometimes code is 
eliminated altogether. 

As a result, the source code displayed by the debugger does not correspond exactly 
to the actual code being executed. 

To illustrate, the following example depicts a segment of source code from a 
FORTRAN program as it might appear on a compiler listing or in a screen-mode 
source display. This code segment sets the first 10 elements of array A to the 
value 1/X. 

Line Source Code 


5 DO 100 1=1,10 

6 A(I) = 1/X 

7 100 CONTINUE 

As the compiler processes the source program, it determines that the reciprocal of 
X need only be computed once, not 10 times as the source code specifies, because 
the value of X never changes in the DO-loop. The compiler thus generates 
optimized code equivalent to the following code segment: 

Line Optimized Code Equivalent 


5 TEMP = 1/X 

DO 100 1=1,10 

6 A(I) = TEMP 

7 100 CONTINUE 

In the optimized code, the value of 1/X is computed once, saved in a temporary 
location, and then assigned to each A(I). The optimized code now executes faster, 
but it no longer corresponds exactly to the source code. 

In this example, if you execute to line 5 by entering a STEP command, the 
debugger displays the source line as it appears in the source file, not the 
optimized code equivalent that it is actually executing. 
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stepped to PROG_\!LINE 5 

5: DO 100 1=1,10 

At this point, if you enter another STEP command to execute line 5, the debugger 
executes line 5 of the optimized code, not line 5 of the displayed source code. 
Thus, the program computes the reciprocal of X and sets up the DO loop, whereas 
the source display indicates only that the DO loop is set up. 

This discrepancy is not obvious from looking at the displayed source line. 
Furthermore, if the computation of 1/X were to fail because X is zero, it would 
appear from inspecting the source display that a division by zero had occurred on 
a source line that contains no division at all. 

This kind of apparent mismatch between source code and executable code should 
be expected from time to time when debugging optimized programs. It can be 
caused not only by code motions out of loops, as in the previous example, but by a 
number of other optimization methods as well. 

9.1.3 Use of Registers 

A compiler might determine that the value of an expression does not change 
between two given occurrences and might save the value in a register. In such 
cases, the compiler does not recompute the value for the next occurrence, but 
assumes the value saved in the register is valid. 

If, while debugging a program, you use the DEPOSIT command to change the 
value of the variable in the expression, the corresponding value stored in the 
register might not be changed. Thus, when execution continues, the value in the 
register might be used instead of the changed value in the expression, causing 
unexpected results. 

In addition, when the value of a nonstatic variable (see Section 3.6.2) is held in 
a register, its value in memory is generally invalid; therefore, a spurious value 
might be displayed if you enter the EXAMINE command for a variable under 
these circumstances. 

9.1.4 Use of Condition Codes 

One optimization technique takes advantage of the way in which the VAX 
processor condition codes are set. For example, consider the following Pascal 
source code: 

X := X + 2.5; 

IF X < 0 
THEN 

Rather than test the new value of X to determine whether to branch, the 
optimized code bases its decision on the condition code setting after 2.5 is added 
to X. Thus, if you attempt to set a breakpoint on the IF statement and deposit 
a different value into X, you do not achieve the intended result because the 
condition codes no longer reflect the value of X. In other words, the decision to 
branch is being made without regard to the deposited value of the variable. 

Again, you can use the EXAMINE/OPERAND .%PC command to determine the 
correct location for depositing so as to achieve the desired effect. 
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9.2 Debugging Screen-Oriented Programs 

The debugger uses the terminal screen for input and output (I/O) during a 
debugging session. If you use a single terminal to debug a screen-oriented 
program that uses most or all of the screen, debugger I/O can overwrite, or can be 
overwritten by, program I/O. 

Using one terminal for both program I/O and debugger I/O is even more 
complicated if you are debugging in screen mode and your screen-oriented 
program calls any VMS RTL Screen Management (SMG$) routines. This is 
because the debugger’s screen mode also calls SMG routines. In such cases, the 
debugger and your program share the same SMG pasteboard, causing further 
interference. 

To avoid these problems when debugging a screen-oriented program, use one of 
the following techniques to separate debugger I/O from program I/O: 

• If you are at a workstation running VWS, start your debugging session and 
then enter the debugger command SET MODE SEPARATE. It creates a 
separate terminal-emulator window for debugger I/O. Program I/O continues 
to be displayed in the window from which you invoked the debugger. 

• If you are at a workstation running DECwindows and want to display the 
debugger’s DECwindows interface on a separate workstation (also running 
DECwindows), see Section 1.6.3.1. 

• If you are at a workstation running DECwindows but want to use the 
debugger’s command interface rather than the DECwindows interface, see 
Section I.6.3.3. It explains how to create a separate DECterm window 
for debuger I/O. The effect is similar to using the command SET MODE 
SEPARATE on a workstation running VWS. 

• If you do not have a workstation, use two terminals—one for program I/O 
and another for debugger I/O. The technique is described in the rest of this 
section. 

Assume that TTD1: is your current terminal, from which you plan to invoke the 
debugger. You want to display debugger I/O on terminal TTD2: so that TTD1: is 
devoted exclusively to program I/O. 

Follow these steps: 

1. Provide the necessary protection to TTD2: so that you can allocate that 
terminal from TTD1: (see Section 9.2.1). 

The remaining steps are all performed from TTD1:. 

2. Allocate TTD2:. This provides your process on TTD1: with exclusive access to 
TTD2:: 

$ ALLOCATE TTD2: 

3. Assign the debugger logical names DBG$INPUT and DBG$OUTPUT to 
TTD2:: 

$ DEFINE DBG$INPUT TTD2: 

$ DEFINE DBG$OUTPUT TTD2: 

DBG$INPUT and DBG$OUTPUT specify the debugger input device and 
output device, respectively. By default, these logical names are equated to 
SYS$INPUT and SYS$OUTPUT, respectively. Assigning DBG$INPUT and 
DBG$OUTPUT to TTD2: enables you to display debugger commands and 
debugger output on TTD2:. 
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4. Make sure that the terminal type is known to the system. Use the follow ing 
command: 

$ SHOW DEVICE/FULL TTD2: 

If the device type is "unknown," your system manager (or a user with LOG_ 
10 or PHY_IO privilege) must make it known to the system as shown in the 
following example. In the example, the terminal is assumed to be a VT200: 

$ SET TERMINAL/PERMANENT/DEVICE=VT200 TTD2: 

5. Run the program to be debugged: 

$ RUN FORMS 

You can now observe debugger I/O on TTD2: 

6. When finished with the debugging session, deallocate TTD2: as follows (or log 
out): 

$ DEALLOCATE TTD2: 

9.2.1 Setting the Protection to Allocate a Terminal 

On a properly secured system, terminals are protected so that you cannot allocate 
a terminal from another terminal. 

To set the nessary protection, your system manager (or a user with the privileges 
indicated) should follow the steps illustrated in the following example. 

In the example, TTD1: is your current terminal (from which you plan to invoke 
the debugger), and TTD2: is the terminal to be allocated so that it can display 
debugger I/O. 

1. If both TTD1: and TTD2: are hardwired to the system, go to step 4. 

If TTD1: and TTD2: are connected to the system over a LAT (local area 
transport), continue with step 2. 

2. Log in to TTD2: 

3. Enter these commands (you need LOG_IO or PHY_IO privilege): 

$ SET PROCESS/PRIV=LOG_IO 
$ SET TERMINAL/NOHANG/PERMANENT 
$ LOGOUT/NOHANG 

4. Enter one of the following commands (you need OPER privilege): 

$ SET ACL/OBJECT_TYPE=DEVICE/ACL=(IDENT=[PROJ,JONES],ACCESS=READ+WRITE) TTD2: O 
$ SET PROTECTION=WORLD:RW/DEVICE TTD2: © 

O The SET ACL command line is preferred because it uses an access control 
list (ACL). In the example, access is restricted to UIC [PROJ,JONES]. 

0 The SET PROTECTION command line provides world read/write access 
and, therefore, allows any user to allocate and perform I/O to TTD2:. 

9.3 Debugging Multilanguage Programs 

The debugger enables you to debug modules whose source code is written in 
different languages, within the same debugging session. This section highlights 
some language-specific behavior that you should be aware of, to minimize possible 
confusion. 
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When debugging in any language, be sure to consult 

• Appendix E, which summarizes debugger support for each language. 

• The documentation supplied with that language. 

9.3.1 Controlling the Current Debugger Language 

At debugger startup, the debugger sets the current language to that in which 
the module containing the main program (usually the routine containing the 
image transfer address) is written. The current language is identified when you 
invoke the debugger. For example: 

$ RUN FORMS 

VAX DEBUG Version 5.5 

%DEBUG-I-INITIAL, language is PASCAL, module set to FORMS 
DBG> 

The current language setting determines how the debugger parses and interprets 
the names, operators, and expressions you specify in debugger commands, 
including things like the typing of variables, array and record syntax, the default 
radix for integer data, case sensitivity, and so on. The language setting also 
determines how the debugger displays data associated with your program. 

Many programs include modules that are written in languages other than that 
of the main program. To minimize confusion, by default the debugger language 
remains set to the language of the main program throughout a debugging session, 
even if execution is suspended within a module written in another language. 

To take full advantage of symbolic debugging with such modules, use the SET 
LANGUAGE command to set the debugging context to that of another language. 
For example, the following command causes the debugger to interpret any 
symbols, expressions, and so on according to the rules of the COBOL language: 

DBG> SET LANGUAGE COBOL 

The keywords that you can use with the SET LANGUAGE command correspond 
to all of the VMS supported languages that are also supported by the debugger: 

ADA 

BASIC 

BLISS 

C 

COBOL 

DIBOL 

FORTRAN 

MACRO 

PASCAL 

PLI 

RPG 

SCAN 

In addition, when debugging a program that is written in an unsupported 
language, you can specify the SET LANGUAGE UNKNOWN command. To 
maximize the usability of the debugger with unsupported languages, the SET 
LANGUAGE UNKNOWN command causes the debugger to accept a large set of 
data formats and operators, including some that might be specific to only a few 
supported languages. The operators and constructs that are recognized when the 
language is set to UNKNOWN are identified in Appendix E. 
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9.3.2 Specific Differences Among Languages 

This section lists some of the differences you should keep in mind when debugging 
in various languages. Included are differences that are affected by the SET 
LANGUAGE command and other differences (for example, language-specific 
initialization code and predefined breakpoints). 

This list is not intended to be complete. See Appendix E and your language 
documentation for complete details. 

9.3.2.1 Default Radix 

The default radix for entering and displaying integer data is hexadecimal for 
BLISS and MACRO and decimal for all other languages. 

Use the SET RADIX command to establish a new default radix. 

9.3.2.2 Evaluating Language Expressions 

Several debugger commands and constructs evaluate language expressions: 

• The EVALUATE, DEPOSIT, IF, FOR, REPEAT, and WHILE commands. 

• WHEN clauses, which are used with the SET BREAK, SET TRACE, and SET 
WATCH commands. 

When processing these commands, the debugger evaluates language expressions 
in the syntax of the current language and in the current radix as discussed in 
Section 4.1.5. 

Note that operators vary widely among different languages (see Appendix E). For 
example, the following two commands evaluate equivalent expressions in Pascal 
and FORTRAN, respectively: 

DBG> SET WATCH X WHEN (Y < 5) ! Pascal 

DBG> SET WATCH X WHEN (Y .LT. 5) ! FORTRAN 

Assume that the language is set to PASCAL and you have entered the first 
(Pascal) command. You now step into a FORTRAN routine, set the language to 
FORTRAN, and resume execution. While the language is set to FORTRAN, the 
debugger is not able to evaluate the expression (Y < 5). As a result, it sets an 
unconditional watchpoint and, when the watchpoint is triggered, returns a syntax 
error for the "<" operator. 

This type of discrepancy can also occur if you use commands that evaluate 
language expressions in debugger command procedures and initialization files. 

Note also that the debugger processes language expressions that contain variable 
names (or other address expressions) differently when the language is set to 
BLISS than when it is set to another language. See Section 4.1.5 for details. 

9.3.2.3 Arrays and Records 

The syntax for denoting array elements and record components (if applicable) 
varies among languages. 

For example, some languages use brackets, [], and others use parentheses, 0, to 
delimit array elements. 

Some languages (like BASIC) have zero-based arrays. Some languages have 
one-based arrays, as in the following example: 
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DBG> EXAMINE INTEGER_ARRAY 
PR0G2\INTEGER_ARRAY 


(1,1) 

27 

(1,2) 

31 

(1,3) 

12 

(2,1) 

15 

(2,2) 

22 

(2,3) 

18 


DBG> 

For some languages (like Pascal and Ada) the specific array declaration 
determines how the array is based. 

9.3.2.4 Case Sensitivity 

Names and language expressions are case sensitive in C. You must specify 
them exactly as they appear in the source code. For example, the following two 
commands are not equivalent when the language is set to C: 

DBG> SET BREAK SCREEN_IO\%LINE 10 
DBG> SET BREAK screen_io\%LINE 10 

9.3.2.5 Initialization Code 

If you have a multilanguage program that includes an Ada package, or a 
FORTRAN main program that was compiled with the /CHECK=UNDERFLOW 
(or /CHECK=ALL) qualifier, a NOTATMAIN message is issued when you invoke 
the debugger. For example: 

$ RUN MONITOR 

VAX DEBUG Version 5.5 

%DEBUG-I-INITIAL, language is ADA, module set to MONITOR 
%DEBUG-I-NOTATMAIN, type GO to get to start of main program 
DBG> 

The NOTATMAIN message indicates that execution is suspended before the 
beginning of the main program. This enables you to execute and check some 
initialization code under debugger control. 

The initialization code is created by the compiler and is placed in a special 
PSECT named LIB$INITIALIZE. In the case of an Ada package, the initialization 
code belongs to the package body (which might contain statements to initialize 
variables, and so on). In the case of a FORTRAN program, the initialization code 
declares the handler that is needed if you specify the /CHECK=UNDERFLOW or 
/CHECK=ALL qualifier. 

The NOTATMAIN message indicates that, if you do not want to debug the 
initialization code, you can execute immediately to the beginning of the main 
program by entering a GO command. You are then at the same point as when 
you invoke the debugger with any other program. Entering the GO command 
again starts program execution. 

9.3.2.6 Ada Predefined Breakpoints 

If your program is linked with a module that is written in Ada, two breakpoints 
that are associated with Ada tasking exception events are automatically 
established when you invoke the debugger. Note that these breakpoints are 
not affected by a SET LANGUAGE command. They are established automatically 
during debugger initialization when the Ada Run-Time Library is present. When 
you enter a SHOW BREAK command under these conditions, the following 
breakpoints are displayed: 
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DBG> SHOW BREAK 

Predefined breakpoint on ADA event "EXCEPTION_TERMINATED" for any value 
Predefined breakpoint on ADA event "DEPENDENTS EXCEPTION" for any value 
DBG> 

9.4 Debugging Exceptions and Condition Handlers 

A condition handler is a procedure that the VMS operating system executes when 
an exception occurs. 

Exceptions include hardware conditions (such as an arithmetic overflow or 
a memory access violation) or signaled software exceptions (for example, an 
exception signaled because a file could not be found). 

VMS conventions specify how, and in what order, various condition handlers 
established by the operating system, the debugger, or your own program are 
invoked—for example, the primary handler, call frame (application-declared) 
handlers, and so on. Section 9.4.3 describes condition handling when you 
are using the debugger. See the VMS Run-Time Library Routines Volume for 
additional general information about condition handlin g 

Tools for debugging exceptions and condition handlers include the following: 

• The SET BREAK/EXCEPTION and SET TRACE/EXCEPTION commands, 
which direct the debugger to treat any exception generated by your 
program as a breakpoint or tracepoint, respectively (see Section 9.4.1 
and Section 9.4.2). 

• Several built-in symbols (such as %EXC_NAME), which enable you to qualify 
exception breakpoints and tracepoints (see Section 9.4.4). 

• The SET BREAK/EVENT and SET TRACE/EVENT commands, which enable 
you to break on or trace exception events that are specific to Ada and SCAN 
programs (see the corresponding documentation for more information). 

9.4.1 Setting Breakpoints or Tracepoints on Exceptions 

When you enter a SET BREAK/EXCEPTION (or SET TRACE/EXCEPTION) 
command, you direct the debugger to treat any exception generated by 
your program as a breakpoint (or tracepoint). As a result of a SET BREAK 
/EXCEPTION command, if your program generates an exception, the debugger 
suspends execution, reports the exception and the line where execution is 
suspended, and prompts for commands. The following example illustrates the 
effect: 

DBG> SET BREAK/EXCEPTION 
DBG> GO 


%SYSTEM-F-INTDIV, arithmetic trap, integer divide by zero at PC=0000066C, PSL=03C00022 
break on exception preceding TEST\%LINE 13 
6: X := 3/Y; 

DBG> 

Note that an exception breakpoint (or tracepoint) is triggered even if your 
program has a condition handler to handle the exception. The SET BREAK 
/EXCEPTION command causes a breakpoint to occur before any handler can 
execute (and thereby possibly dismiss the exception). Without the exception 
breakpoint, the handler would be executed, and the debugger would get control 
only if no handler dismissed the exception (see Section 9.4.2 and Section 9.4.3). 
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The following command line is useful for identifying where an exception occurred. 
It causes the debugger to display automatically the sequence of active calls and 
the PC value at an exception breakpoint. 

DBG> SET BREAK/EXCEPTION DO (SET MODULE/CALLS; SHOW CALLS) 

You can also create a screen-mode DO display that issues a SHOW CALLS 
command whenever the debugger interrupts execution. For example: 

DBG> DISPLAY CALLS DO (SET MODULE/CALLS; SHOW CALLS) 

An exception tracepoint (established with the SET TRACE/EXCEPTION 
command) is like an exception breakpoint followed by a GO command without an 
address expression specified. 

An exception breakpoint cancels an exception tracepoint, and vice versa. 

To cancel exception breakpoints or tracepoints, use the CANCEL BREAK 
/EXCEPTION or CANCEL TRACE/EXCEPTION command, respectively. 

9.4.2 Resuming Execution at an Exception Breakpoint 

When an exception breakpoint is triggered, execution is suspended before any 
application-declared condition handler is invoked. When you resume execution 
from the breakpoint with the GO, STEP, or CALL commands, the behavior is as 
follows: 

• Entering a GO command without an address-expression parameter, or 
entering a STEP command, causes the debugger to resignal the exception. 
The GO command enables you to observe which application-declared handler, 
if any, next handles the exception. The STEP command causes you to step 
into that handler (see the next example). 

• Entering a GO command with an address-expression parameter causes 
execution to resume at the specified location, thus inhibiting the execution of 
any application-declared handlers. 

• A common debugging technique at an exception breakpoint is to call a dump 
routine with the CALL command (see Chapter 8). When you enter the 
CALL command at an exception breakpoint, no breakpoints, tracepoints, or 
watchpoints that were previously set within the called routine are active, so 
that the debugger does not lose the exception context. After the routine has 
executed, the debugger prompts for input. Entering a GO or STEP command 
at this point causes the debugger to resignal the exception, as for the first 
bulleted item in this list. 

The following FORTRAN example shows how to determine the presence of a 
condition handler at an exception breakpoint and how a STEP command, entered 
at the breakpoint, enables you to step into the handler. 

At the exception breakpoint, the SHOW CALLS command indicates that the 
exception was generated during a call to routine SYS$QIOW: 
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DBG> SET BREAK/EXCEPTION 
DBG> GO 


-sSYSTEM-F-SSFAIL, system service failure exception, status=0000013C, PC=7FFEDE06, PSL=03C00000 
break on exception preceding SYS$QI0W+6 
DBG> SHOW CALLS 

module name routine name line rel PC abs PC 

SYS$QIOW 00000006 7FFEDE06 

*EXC$MAIN EXC$MAIN 23 0000003B 0000063B 

DBG> 

The following SHOW STACK command indicates that no handler is declared in 
routine SYS$QIOW. However, one level down the call stack, routine EXC$MAIN 
has declared a handler named SSHAND: 


DBG> SHOW STACK 
stack frame 0 (2146296644) 
condition handler: 0 


SPA: 

S: 

mask: 

PSW: 

saved AP: 
saved FP: 
saved PC: 


0 

0 

A M<R2,R3,R4,R5,R6,R7,R8,R9,R10,R11> 
0020 (hexadecimal) 

2146296780 
2146296704 
EXC$MAIN\%LINE 25 


stack frame 1 
condition 
SPA: 

S: 

mask: 

PSW: 

saved AP: 
saved FP: 
saved PC: 


(2146296704) 
handler: SSHAND 
0 
0 

A M<R11> 

0000 (hexadecimal) 
2146296780 
2146296760 
SHARE$DEBUG+2217 


At this exception breakpoint, entering a STEP command enables you to step 
directly into condition handler SSHAND: 

DBG> STEP 

stepped to routine SSHAND 

2: INTEGER*4 FUNCTION SSHAND (SIGARGS, MECHARGS) 

DBG> SHOW CALLS 

module name routine name line rel PC abs PC 

*SSHAND SSHAND 2 00000002 00000642 

- above condition handler called with exception 0000045C: 

%SYSTEM-F-SSFAIL, system service failure exception, status=0000013C, PC=7FFEDE06, PSL=03C00000 

- end of exception message 

SYS$QIOW 00000006 7FFEDE06 

*EXC$MAIN EXC$MAIN 23 0000003B 0000063B 

DBG> 

The debugger symbolizes the addresses of condition handlers into names if that 
is possible. However, note that with some languages, exceptions are first handled 
by an RTL routine, before any application-declared condition handler is invoked. 
In such cases, the address of the first condition handler might be symbolized to 
an offset from an RTL shareable image address. 
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9.4.3 Effect of Debugger on Condition Handling 

When you run your program with the debugger, at least one of the following 
condition handlers is invoked, in the order given, to handle any exceptions caused 
by the execution of your program: 

1. Primary handler. 

2. Secondary handler. 

3. Call-frame handlers (application-declared). Also known as stack handlers. 

4. Final handler. 

5. Last-chance handler. 

6. Catchall handler. 

A handler can return one of the following three status codes to the VAX Condition 
Handling Facility: 

• SS$_RESIGNAL—The VMS operating system searches for the next handler. 

• SS$_CONTINUE—The condition is assumed to be corrected, and execution 
continues. 

• SS$_UNWIND—The call stack is unwound some number of frames, if 
necessary, and the signal is dismissed. 

For more information about condition handling, see the VMS Run-Time Library 
Routines Volume . 

9.4.3.1 Primary Handler 

When you run your program with the debugger, the primary handler is the 
debugger. Therefore, the debugger has the first opportunity to handle an 
exception, whether or not the exception is caused by the debugger (Section 3.7 
describes how the debugger causes exceptions to occur in your program in order 
to control and monitor execution). 

If you have entered a SET BREAK/EXCEPTION or SET TRACE/EXCEPTION 
command, the debugger breaks on (or traces) any exceptions caused by your 
program. The break (or trace) action occurs before any application-declared 
handler is invoked. 

If you have not entered a SET BREAK/EXCEPTION or SET TRACE/EXCEPTION 
command, the primary handler resignals any exceptions caused by your program. 

9.4.3.2 Secondary Handler 

The secondary handler is used for special purposes and does not apply to the 
types of programs covered in this manual. 

9.4.3.3 Call-Frame Handlers (Application-Declared) 

Each routine of your program can establish a condition handler, also known as 
a call-frame handler. The operating system searches for these handlers starting 
with the routine that is currently executing. If no handler was established for 
that routine, the system searches for a handler established by the next routine 
down the call stack, and so on back to the main program, if necessary. 
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After it is invoked, a handler might perform one of the following actions: 

• It handles the exception, thus allowing the program to continue execution. 

• It resignals the exception. The operating system then searches for another 
handler down the call stack. 

• It encounters a breakpoint or watchpoint, thereby suspending execution at 
the breakpoint or watchpoint. 

• It generates its own exception. In this case, the primary handler is invoked 
again. 

• It exits, thus terminating program execution. 

9.4.3.4 Final and Last-Chance Handlers 

These handlers are controlled by the debugger. They enable the debugger to 
ultimately regain control and display the DBG> prompt if no application-declared 
handler has handled an exception. Otherwise, the debugging session would 
terminate, and control would pass to the DCL command interpreter. 

The final handler is the last frame on the call stack and the first of these two 
handlers to be invoked. The following example illustrates what happens when 
an unhandled exception is propagated from an exception breakpoint to the final 
handler: 

DBG> SET BREAK/EXCEPTION 
DBG> GO 


%SYSTEM-F-INTDIV, arithmetic trap, integer divide by zero at PC=0000066C, PSL=03C00022 
break on exception preceding TEST\%LINE 13 
6: X := 3/Y; 

DBG> GO 

ISYSTEM-F-INTDIV, arithmetic trap, integer divide by zero at PC=0000066C, PSL=03C00022 
DBG> 

In this example, the first INTDIV message is issued by the primary handler, and 
the second is issued by the final handler, which then displays the DBG> prompt. 

The last-chance handler is invoked only if the final handler cannot g ain control 
because the call stack is corrupted. For example: 

DBG> DEPOSIT %FP = 10 
DBG> GO 


%SYSTEM-F-ACCVIO, access violation, reason mask=00, virtual address=0000000A, PC=0000319C, PSL=03C00000 

%DEBUG-E-LASTCHANCE, stack exception handlers lost, re-initializing stack 

DBG> 

The catchall handler, which is part of the VMS operating system, is invoked if the 
last-chance handler cannot gain control. The catchall handler produces a register 
dump. This should never occur if the debugger has control of your program. 

But it can occur if your program encounters an error when running without the 
debugger. 

If, during a debugging session, you observe a register dump and are returned to 
DCL level, submit an SPR to Digital. 
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9.4.4 Exception-Related Built-In Symbols 

When an exception is signaled, the debugger sets the following exception-related 
built-in symbols. 


Symbol 

Description 

%EXC_FACILITY 

%EXC_NAME 

%ADAEXC_NAME 

%EXC_NUMBER 

%EXC_SEVERITY 

Name of facility that issued the current exception 

Name of current exception 

Ada exception name of current exception (for Ada programs only) 
Number of current exception 

Severity code of current exception 


You can use these symbols as follows: 

• To obtain information about the fields of the VMS condition code of the 
current exception. 

• To qualify exception breakpoints (or tracepoints) so that they trigger only on 
certain kinds of exceptions. 

The following examples illustrate the use of some of these symbols. Note that the 
conditional expressions in the WHEN clauses are language specific: 

DBG> EVALUATE %EXC_NAME 
'ACCVIO' 

DBG> SET TRACE/EXCEPTION WHEN (%EXC_NAME = "ACCVIO") 

DBG> EVALUATE %EXC_FACILITY 
'SYSTEM' 

DBG> EVALUATE %EXC_NUMBER 
12 

DBG> EVALUATE/CONDITI0N_VALUE %EXC_NUMBER 

%SYSTEM-F-ACCVIO, access violation, reason mask=01, virtual address=FFFFFF30, PC=00007552, PSL=03C00000 
DBG> SET BREAK/EXCEPTION WHEN (%EXC_NUMBER = 12) 

DBG> SET BREAK/EXCEPTION WHEN (%EXC_SEVERITY .NE. "I" .AND. %EXC_SEVERITY .NE. "S") 

9.5 Debugging Exit Handlers 

Exit handlers are procedures that are called whenever an image requests the 
$EXIT system service or runs to completion. A user program can declare one or 
more exit handlers. The debugger always declares its own exit handler. 

At program termination, the debugger exit handler executes after all application- 
declared exit handlers have executed. 

To debug an application-declared exit handler, proceed as follows: 

1. Set a breakpoint in that exit handler. 

2. Cause the exit handler to execute, by means of one of the following 
techniques: 

• Include in your program an instruction that invokes the exit handler 
(usually a call to $EXIT). 

• Allow your program to terminate. 

• Enter the EXIT command. (Note that the QUIT command does not 
execute any user declared exit handlers.) 

When the exit handler executes, the breakpoint is activated and control is 
then returned to the debugger, which prompts for commands. 
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The SHOW EXIT_HANDLERS command gives a display of the exit handlers 
that your program has declared. The exit handler routines are displayed in 
the order that they are called. A routine name is displayed symbolically, if 
possible. Otherwise its address is displayed. The debugger’s exit handlers are not 
displayed. For example: 

DBG> SHOW EXIT_HANDLERS 
exit handler at STACKS\CLEANUP 
exit handler at BLIHANDLER\HANDLER1 
DBG> 

9.6 Debugging AST-Driven Programs 

A program can use asynchronous system traps (ASTs) either explicitly, or 
implicitly by calling VMS system services or RTL routines that call application- 
defined AST routines. Section 9.6.1 explains how to facilitate debugging by 
disabling and enabling the delivery of ASTs originating with your program. 
Section 9.6.2 explains how delivery of an AST affects a SHOW CALLS display. 

9.6.1 Disabling and Enabling the Delivery of ASTs 

Debugging AST-driven programs can be confusing because interrupts originating 
from the program being debugged can occur, but are not processed, while 
the debugger is running (processing commands, tracing execution, displaying 
information, and so on). 

By default, the delivery of ASTs is enabled while the program is running. The 
DISABLE AST command disables the delivery of ASTs while the program is 
running and causes any such potential interrupts to be queued. 

The delivery of ASTs is always disabled when the debugger is running. 

The ENABLE AST command reenables the delivery of ASTs, including any 
pending ASTs. The command SHOW AST indicates whether the delivery of ASTs 
is enabled or disabled. 

To control the delivery of ASTs during the execution of a routine called with 
the CALL command, use the /[NO]AST qualifiers. The command CALL/AST 
enables the delivery of ASTs in the called routine. The command CALL/NOAST 
disables the delivery of ASTs in the called routine. If you do not specify /AST or 
/NOAST with the CALL command, the delivery of ASTs is enabled unless you 
have previously entered the DISABLE AST command. 

9.6.2 Call Frames Associated with ASTs in SHOW CALLS Display 

The delivery of an AST creates one or more special call frames that appear in a 
SHOW CALLS display. These call frames are not symbolized and might make 
the SHOW CALLS display confusing. The following example illustrates what you 
might see in a SHOW CALLS display when an AST routine is on the call stack. 

Assume that a program calls the system service $SETIMR to set a timer that 
expires at a specified interval and then execute an application-defined AST 
routine, TIMER_ROUT, in the program. 

The following command lines set a breakpoint on routine TIMER_ROUT, start 
execution which is then suspended on that routine, and display the sequence of 
active calls at the breakpoint: 
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DBG> SET BREAK TIMER_ROUT 
DBG> GO 

break at routine M0D1\TIMER_R0UT 


141 X = .X + 1 • 

DBG> SHOW CALLS 




module name routine name 

line 

rel PC 

abs PC 

*M0D1 TIMER_ROUT 

14 

00000002 

0000040E 

DBG> 


00000000 

80009E5E 


The bottom line is the call frame associated with the system AST dispatcher. 

It shows the absolute PC value when the AST was delivered. Because the AST 
dispatcher is in system space (as indicated by the high absolute address), no 
symbolic information (module name, routine name, line number) is available. 

A SHOW CALLS display associated with the delivery of an AST might also 
show some debugger call frames (module name SHARE$DEBUG) and diagnostic 
messages related to condition handling by the debugger. You should ignore such 
messages and call frames. 
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Debugging Multiprocess Programs 


This chapter describes features of the debugger that are specific to multiprocess 
programs (programs that run in more than one process). The features enable you 
to display process information and control the execution of specific processes. Use 
these features in addition to those explained in other chapters. 

The first section gets you started with multiprocess debugging. The remaining 
sections provide additional information. 

Throughout the chapter it is assumed that all images discussed are "debuggable" 
images—that is, images that can be brought under control of the debugger. A 
debuggable image is one that was not linked with the /NOTRACEBACK qualifier. 
As explained in Chapter 5, you have full symbolic information when debugging an 
image only if its modules were compiled and linked with the /DEBUG qualifier. 

10.1 Getting Started 

This section gives an overview of the multiprocess debugging environment and 
explains the basic techniques used to debug a multiprocess program. Refer to 
subsequent sections for additional details. 

10.1.1 Establishing a Multiprocess Debugging Configuration 

Before invoking the debugger, enter the following command to establish a 
multiprocess configuration: 

$ DEFINE/JOB DBG$PR0CESS MULTIPROCESS 

This command establishes a multiprocess configuration for the VMS job hierarchy 
in which the command was entered. As a result, after a debugging session is 
started, any debuggable image running in the same job can be controlled from 
that one session. 

See Section 10.2.1 for more information about debugging configurations and 
process relationships. See Section 10.2.9 for system requirements related to 
multiprocess debugging. 

10.1.2 Invoking the Debugger 

This section explains the usual way of starting a multiprocess debugging session. 
See Section 10.2.4 for additional techniques for invoking the debugger (for 
example, using the Ctrl/Y-DEBUG sequence or the CONNECT command). 

You typically initiate the execution of a multiprocess program by running the 
main image in the main (master) process. After the main image is r unning in 
the main process, the program might spawn one or more subprocesses to run 
additional images by issuing a LIB$SPAWN run-time library call or a $CREPRC 
system service call. 
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If the main image is debuggable, the debugger is invoked when you run the 
image. For example: 

$ RUN MAIN_PR0G 

VAX DEBUG Version 5.5 

IDEBUG-I-INITIAL, language is FORTRAN, module set to MAIN_PR0G 
%DEBUG-I-NOTATMAIN, type GO to get to start of main program 
predefined trace on activation at routine MAIN_PR0G in %PROCESS_NUMBER 1 
DBG_1> 

As with a one-process program, the debugger displays its banner and prompt just 
prior to the start of execution of the main image. However, note two differences: 
the "predefined trace on . . . " message and the debugger prompt. 

In a multiprocess configuration, the debugger traces each new process that is 
brought under control. In this case, the debugger traces the first process, which 
runs the main image of the program. (%PROCESS_NUMBER is a built-in symbol 
that identifies a process number, just as %LINE identifies a line number.) 

The significance of the prompt suffix ('_1') is explained in the next section. 

10.1.3 Visible Process and Process-Specific Commands 

The previous example shows that the debugger prompt in a multiprocess 
debugging configuration is different from that found in the default configuration. 

In a multiprocess configuration, "dynamic prompt setting" is enabled by default 
(SET PROMPT/SUFFIX=PROCESS_NUMBER). Therefore, the prompt has a 
process-specific suffix that indicates the process number of the visible process. 
The debugger assigns a process number sequentially, starting with process 1, to 
each process that comes under the control of a given debugging session. 

The visible process is the process that is the default context for issuing process- 
specific commands. Process-specific commands are those that start execution 
(STEP, GO, and so on) and those used for looking up symbols, setting breakpoints, 
looking at the call stack and registers, and so on. Commands that are not process 
specific are those that do not depend on the mapping of memory but, rather, affect 
the entire debugging environment (for example, keypad mode and screen mode 
commands). 

Unless dynamic prompt setting is disabled (SET PROMPT/NOSUFFIX), the 
debugger prompt suffix always identifies the visible process (for example, DBG_ 
1>). The SET PROMPT command provides several options for tailoring the 
prompt-string prefix and suffix to your needs. 

10.1.4 Obtaining Information About Processes 

Use the SHOW PROCESS command to obtain information about processes 
that are currently under control of your debugging session. By default, SHOW 
PROCESS displays one line of information about the visible process. The 
following example shows the kind of information displayed immediately after you 
invoke the debugger: 

DBG_1> SHOW PROCESS 

Number Name Hold State Current PC 

* 1 JONES activated MAIN_PR0G\%LINE 2 

DBG 1> 
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A one-line SHOW PROCESS display provides the following information about 

each process specified: 

• The process number assigned by the debugger. In this case, the process 
number is 1 because this is the first process known to the debugger. The 
asterisk in the leftmost column (*) marks the visible process. 

• The VMS process name. In this case, the VMS process name is JONES. 

• Whether the process has been put on hold with a SET PROCESS/HOLD 
command, as explained in Section 10.1.7.2. (This process has not been put on 
hold.) 

• The current debugging state for that process. A process is in the "activated" 
state when it is first brought under debugger control (that is, before it has 
executed any part of the program under debugger control). Table 10-1 
summarizes the possible debugging states that can appear in the state 
column. 

• The location (symbolized, if possible) where execution of the image is 
suspended in that process. In this case, the image has not started execution. 


Table 10-1 Debugging States 


State 

Description 

Activated 

The image and its process have just been brought under 
debugger control, either through a DCL RUN/DEBUG 
command, a debugger CONNECT command, a Ctrl/Y- 
DEBUG sequence, or by the program signaling SS$_ 
DEBUG while it was not under debugger control. 

Break 1 

A breakpoint was triggered. 

Interrupted 

Execution was interrupted in that process, either because 
execution was suspended in another process, or because 
the user interrupted execution with the abort-key sequence 
(Ctrl/C, by default). 

Step 1 

A STEP command has completed. 

Terminated 

The image has terminated execution but the process is 
still under debugger control. Therefore, you can obtain 
information about the image and its process. 

Trace 1 

A tracepoint was triggered. 

Unhandled exception 

An unhandled exception was encountered. 

Watch of 

A watchpoint was triggered. 

1 See the SHOW PROCESS command in the command dictionary for a list of additional states. 


The SHOW PROCESS/ALL command provides information about all processes 
that are currently under debugger control (in the case of the previous example, 
a SHOW PROCESS/ALL command would show only process 1). The SHOW 
PROCESS/FULL command provides additional details about processes. 

Returning to the previous example, if you now enter a STEP command followed 
by a SHOW PROCESS command, the state column in the SHOW PROCESS 
display indicates that execution is suspended at the completion of a step: 
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DBG_1> SHOW PROCESS 

Number Name Hold State Current PC 

* 1 JONES step MAIN_PROG\%LINE 3 

DBG_1> 

Similarly, if you were to set a breakpoint and enter a GO command, a SHOW 
PROCESS command entered at the prompt after the breakpoint has triggered 
would identify the state as "break". 

10.1.5 Bringing a Spawned Process Under Debugger Control 

Continuing with the example from the last section, assume that you have entered 
a few more STEP commands and, in the middle of a step, MAIN_PROG spawns a 
process to run a debuggable image called TEST. 

Because DBG$PROCESS has the value MULTIPROCESS, the spawned process is 
now requesting to connect to the current debugging session, and the image TEST 
is suspended at the start of execution. 

While the spawned process is waiting to be connected, it is not yet known to the 
debugger and cannot be identified in a SHOW PROCESS/ALL display. You can 
bring the process under debugger control using either of the following methods: 

• Enter a command, such as STEP, that starts execution. 

• Enter the CONNECT command without specifying a parameter. The 
CONNECT command is preferable in cases when you do not want the 
program to execute further. 

The following example illustrates use of the CONNECT command: 

DBG_1> STEP 

stepped to MAIN_PR0G\%LINE 18 in %PROCESS_NUMBER 1 
18: LIBSSPAWN("RUN/DEBUG TEST") 

DBG_1> STEP 

stepped to MAIN_PROG\%LINE 21 in %PROCESS_NUMBER 1 
21: X = 7 

DBG_1> CONNECT 

predefined trace on activation at routine TEST in %PROCESS_NUMBER 2 
DBG_1> 

In this example, the second STEP command takes you past the LIB$SPAWN call 
that spawns the process. The CONNECT command brings the waiting process 
under debugger control. After entering the CONNECT command, you might 
need to wait a moment for the process to connect. The "predefined trace on ... " 
message, as explained in Section 10.1.2, indicates that the debugger has taken 
control of a new process and identifies that process as process 2, the second 
process known to the debugger in this session. 

A SHOW PROCESS/ALL command, entered at this point, identifies the debugging 
state for each process and the location at which execution is suspended: 

DBG_1> SHOW PROCESS/ALL 
Number Name Hold State 

* 1 JONES step 

2 J0NES_1 activated 

DBG_1> 

Note that the CONNECT command brings any processes that are waiting to be 
connected to the debugger under debugger control. If no processes are waiting, 
you can press Ctrl/C to abort the CONNECT command and display the debugger 
prompt. 


Current PC 
MAIN_PROG\%LINE 21 
TEST\%LINE 1+2 
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10.1.6 Broadcasting Commands to Specified Processes 

By default, process-specific commands are executed in the context of the visible 
process. The DO command enables you to execute commands in the context of 
one or more processes that are currently under debugger control. This is also 
referred to as "broadcasting" commands to processes. 

Use the DO command without a qualifier to execute commands in the context of 
all of the processes. For example, the following command executes the SHOW 
CALLS command for all processes currently under debugger control (processes 1 
and 2, in this case): 

DBGJL> DO (SHOW CALLS) 

For %PR0CESS NUMBER 1 


module name 

routine name 

line 

rel PC 

abs PC 

*MAIN PROG MAIN PROG 

For ^PROCESS NUMBER 2 

21 

0000001E 

0000041E 

module name 

routine name 

line 

rel PC 

abs PC 

TEST 

TEST 

1+2 

0000000B 

0000040B 


As indicated in this example, the debugger identifies the process associated with 
any debugger output. 

Use the DO command with the /PROCESS= qualifier to execute commands in the 
context of specific processes. For example, the following command executes the 
SET MODULE START and EXAMINE X commands in the context of process 2: 

DBG_1> D0/PR0CESS=(%PR0C 2) (SET MODULE START; EXAMINE X) 

For more information about how to specify processes in debugger commands, see 
Section 10.2.2. 

10.1.7 Controlling Execution 

Program execution in a multiprocess debugging environment follows these 
conventions: 

• When you enter a command that starts program execution, such as STEP or 
GO, the command is executed in the context of the visible process. However, 
images in any other processes that have not been put on hold (with a SET 
PROCESS/HOLD command) are also allowed to execute. Similarly, if you use 
the DO command to broadcast a command to start execution in one or more 
processes, the command is executed in the context of each specified process 
that is not on hold, but images in any other processes that are not on hold are 
also allowed to execute. In all cases, a hold condition is ignored in the visible 
process. (See Section 10.1.7.2 for additional information about the behavior of 
processes on hold.) 

• After execution is started, the way in which it continues depends on whether 
the SET MODE [NO]INTERRUPT command was entered. By default (SET 
MODE INTERRUPT), execution continues until it is suspended in any 
process. At that point, execution is interrupted in any other processes that 
were executing images, and the debugger prompts for input. 

These concepts are illustrated next by continuing with the example in 
Section 10.1.5 that illustrates the use of the CONNECT command. 

In that example, the "stepped to ... " messages indicate that both commands 
are executed in the context of process 1, the visible process. The second 
STEP command spawns process 2. The SHOW PROCESS/ALL example of 
Section 10.1.5 indicates that execution in processes 1 and 2 is suspended at 
MAIN_PROG\ %LINE 21 and TEST\ %LINE 1+2, respectively. 
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At this point, entering another STEP command followed by SHOW PROCESS 
/ALL results in the following display: 

DBG_1> STEP 

stepped to MAIN_PROG\%LINE 23 in %PROCESS_NUMBER 1 
23: Y = 15 

DBG_1> SHOW PROCESS/ALL 

Number Name Hold State Current PC 

* 1 JONES step MAIN_PROG\%LINE 23 

2 J0NES_1 interrupted TEST\%LINE 3+1 

DBG_1> 

The STEP command is executed in the context of process 1, the visible process. 
After the STEP command, execution in process 1 is suspended at MAIN_ 
PROG\%LINE 23. However, the STEP command also causes execution to start 
in process 2. The completion of the STEP command in process 1 causes execution 
in process 2 to be interrupted at TEST\%LINE 3+1. 

Section 10.1.7.1 describes another mode of execution, which is provided by the 
SET MODE NOINTERRUPT command. 

10.1.7.1 Controlling Execution with SET MODE NOINTERRUPT 

The SET MODE NOINTERRUPT command allows execution to continue without 
interruption in other processes when it is suspended in some process. This is 
especially useful if, for example, you want to broadcast a STEP command to 
several processes with the DO command, then complete execution of the STEP 
command in all these processes. For example: 

DBG_1> SET MODE NOINTERRUPT 
DBG_1> DO (STEP) 

In this example, the DO command executes the STEP command in the context of 
all processes. The visible process and any other processes that are not on hold 
start execution. Because the SET MODE NOINTERRUPT command was entered, 
the prompt is displayed only after the STEP command has completed execution 
(or execution has been otherwise suspended at a breakpoint or watchpoint) in all 
processes that were executing. 

When SET MODE NOINTERRUPT is in effect, as long as execution continues in 
any process, the debugger does not prompt for input. In such cases, use Ctrl/C to 
interrupt all processes and display the prompt. 

10.1.7.2 Putting Specified Processes on Hold 

As indicated in the preceding sections, a command that starts execution is 
executed in the context of the visible process, but it also causes execution to start 
in other processes. If you want to inhibit execution in a process, put it on hold. 
For example, the following SET PROCESS/HOLD command puts process 2 on 
hold. The subsequent STEP command is executed in the context of process 1, the 
visible process. Execution also starts in any other processes that are not on hold, 
but not in process 2: 

DBG_1> SET PROCESS/HOLD %PR0C 2 
DBG_1> STEP 

A SHOW PROCESS display indicates whether a process is on hold. For example: 

DBG_1> SHOW PROCESS/ALL 

Number Name Hold State Current PC 

* 1 JONES step MAIN_PR0G\%LINE 24 

2 J0NES_1 HOLD interrupted TESTULINE 3+1 

DBG 1> 
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To release a process from the hold condition, enter the SET PROCESS/NOHOLD 
command, and specify the process. 

Note that a hold condition is ignored in the visible process. Therefore, the SET 
PROCESS/HOLD/ALL command is a convenient way to confine execution to the 
visible process. In the following example, execution starts only in the visible 
process: 

DBG_1> SET PROCESS/HOLD/ALL 
DBG_1> STEP 

This feature is useful if, for example, you want to use the CALL command to 
execute a dump routine that is not part of the execution stream of your program. 

The preceding discussions also apply if you use the DO command to broadcast 
a GO, STEP, or CALL command to several processes. The GO, STEP or CALL 
command is executed in the context of each specified process that is not on hold, 
and execution also starts in any other process that is not on hold. The following 
example illustrates the execution behavior when all processes are put on hold 
and commands are broadcast to all processes. Execution starts only in the visible 
process (process 1, in this example): 

DBG_1> SET PROCESS/HOLD/ALL 
DBG_1> DO (EXAMINE X; STEP) 

For %PROCESS_NUMBER 1 
MAIN_PR0G\X: 78 

For %PROCESS_NUMBER 2 
TEST\X: 29 

stepped to MAIN_PR0G\%LINE 26 in %PR0CESS NUMBER 1 

26: K = K + 1 

DBG_1> 

10.1.8 Changing the Visible Process 

Use the SET PROCESS command (with the default /VISIBLE qualifier) to 
establish another process as the visible process. For example, the following 
command makes process 2 the visible process: 

DBG_1> SET PROCESS %PR0C 2 
DBG_2> 

In this example, because dynamic prompt setting is enabled by default, the SET 
PROCESS command also has caused the prompt string suffix to change. It now 
indicates that process 2 is the visible process. All process-specific commands 
are now executed in the context of process 2. For example, a SHOW CALLS 
command would display the call stack for the image running in process 2. 

10.1.9 Dynamic Process Setting 

By default, "dynamic process setting" is enabled (SET PROCESS/DYNAMIC). 

As a result, whenever the debugger suspends program execution and displays 
its prompt, the process in which execution is suspended becomes the visible 
process automatically. Dynamic process setting occurs in the following situations: 
when a breakpoint or watchpoint is triggered, at an exception condition, on the 
completion of a STEP command, or when the last process performs an image exit. 

When dynamic process setting is disabled (/NODYNAMIC), the visible process 
remains unchanged until you specify another process with the SET PROCESS 
/VISIBLE command. 
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Dynamic process setting is illustrated in the following example, which also 
illustrates dynamic prompt setting: 

DBG_1> SHOW PROCESS/ALL 

Number Name Hold State Current PC 

* l JONES step MAIN_PR0G\%LINE 22 

2 J0NES_1 interrupted TEST\%LINE 4 

DBG_1> D0/PR0CESS=(%PR0C 2) (SET BREAK %LINE 11) 

DBG 1> GO 


break at TEST\%LINE 11 in %PROCESS_NUMBER 2 
DBG_2> SHOW PROCESS/ALL 

Number Name Hold State Current PC 

1 JONES interrupted MAIN_PROG\%LINE 28 

* 2 J0NES_1 break TEST\%LINE 11 

DBG_2> 

In this example, process 1 is initially the visible process, as indicated by the 
prompt and the SHOW PROCESS display. The DO command sets a breakpoint 
in the context of process 2. Execution is resumed with the GO command and is 
suspended at the breakpoint in process 2. Process 2 is now the visible process, as 
indicated by the prompt and the SHOW PROCESS display. 

If you have entered the SET MODE NOINTERRUPT command and then started 
execution in several processes with the DO command, the prompt is displayed 
only after execution has been suspended in all processes. In this case, the visible 
process remains unchanged, unless the last process performs an image exit (and 
thereby becomes the visible process). 

10.1.10 Monitoring the Termination of Images 

When the main image of a process runs to completion, the process goes into the 
"terminated" debugging state (not to be confused with process termination in the 
VMS sense). This condition is traced by default, as if you had entered the SET 
TRACE/TERMINATING command. 

When a process is in the terminated debugging state, it is still known to the 
debugger and appears in a SHOW PROCESS/ALL display. You can enter 
commands to examine variables, and so on. 

When the last image of the program exits, the debugger gains control and 
displays its prompt. 

10.1.11 Ending the Debugging Session 

To end the entire debugging session, use the EXIT or QUIT command without 
specifying any parameters. 

EXIT executes any exit handlers that are declared in the program. QUIT does 
not. 

Thus, when you do not specify any parameters, the behavior of EXIT and QUIT 
is analogous to their behavior for the default debugging configuration. 
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10.1.12 Terminating Specified Processes 

lb terminate specified processes without ending the debugging session, use 
the EXIT or QUIT command, specifying one or more process specifications as 
parameters. For example, the following command terminates the image running 
in process 2 and terminates the process: 

DBG_3> EXIT IPROC 2 
DBG_3> 

Subsequently, process 2 does not appear in a SHOW PROCESS display. See the 
command dictionary for complete details on the EXIT and QUIT commands. 

10.1.13 Interrupting Program Execution 

Pressing Ctrl/C (or the abort-key sequence established with the SET ABORT_ 
KEY command) interrupts execution in every process that is currently running an 
image. This is indicated as an "interrupted" state in a SHOW PROCESS display. 

As in the default configuration, you can also use Ctrl/C to abort a debugger 
command. 

10.2 Supplemental Information 

This section provides additional details or more advanced concepts and usages 
than those covered in Section 10.1. 

10.2.1 Debugging Configurations and Process Relationships 

You can invoke the debugger in either the default configuration or the 
multiprocess configuration to debug programs that run in either one or 
several processes, respectively. 

The debugging configuration depends on the current definition of the logical name 
DBG$PROCESS, as indicated in the following table. 


Definition of Logical Name 
DBG$PROCESS 

Resulting Debugging Configuration 

Undefined or DEFAULT 

Default (use this configuration with a program that 
runs in one process) 

MULTIPROCESS 

Multiprocess (use this configuration with a program 
that runs in several processes) 


Note that the debugging configuration does not depend on whether the program 
runs in one or several processes. Rather, the value of DBG$PROCESS determines 
whether debuggable images running in different processes can be controlled from 
the same debugging session. 

Before invoking the debugger, enter the DCL command SHOW LOGICAL 
DBG$PROCESS to determine the current definition of DBG$PROCESS and the 
resulting debugging configuration. 
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10.2.1.1 Establishing a Default Debugging Configuration 

To determine the current debugging configuration, use the SHOW LOGICAL 
DBG$PROCESS command. 

In the following example, the output of the command indicates that a default 
debugging configuration is in effect: 

$ SHOW LOGICAL DBG$PROCESS 

%SH0W-S-N0TRAN, no translation for logical name DBG$PROCESS 

If DBG$PROCESS has the value MULTIPROCESS, and you want to debug a 
program that runs in only one process, enter the following command: 

$ DEFINE DBG$PROCESS DEFAULT 

10.2.1.2 Establishing a Multiprocess Debugging Configuration 

The multiprocess debugging configuration enables you to interact with several 
processes from one debugging session. 

Use the following command to establish a multiprocess debugging configuration: 

$ DEFINE/JOB DBG$PROCESS MULTIPROCESS 

As shown in this example, when defining DBG$PROCESS for a multiprocess 
configuration, use a job logical definition so that the definition applies to all 
processes in that job. An image can be connected to (and controlled by) an 
existing multiprocess debugging session only if the process running the image is 
in the same job as the process running the debugging session. 

In the typical multiprocess scenario, the program runs in one master parent 
process and several subprocesses. The debugger is invoked from the master 
process, then the program creates subprocesses during execution (a subprocess 
can also become the parent of another level of subprocesses). 

Another possible scenario is that the program runs in several peer processes. 
There is no master process. This configuration would result if you invoked the 
debugger by running one debuggable image and then used the SPAWN/NOWAIT 
command repeatedly to spawn other processes and run a debuggable image in 
each spawned process. 

10.2.1.3 Process Relationships When Debugging 

The debugger consists of two parts: A relatively small kernel debugger 
image (DEBUG.EXE) and a larger main debugger image (DEBUGSHR.EXE) 
that contains most of the debugger code. This separation reduces potential 
interference between the debugger and the program being debugged. 

The separation also makes it possible to have two debugging configurations: 
a default configuration and a multiprocess configuration. Regardless of the 
configuration, the presence of a main debugger running in some process 
establishes a unique debugging session. 

When you invoke the debugger in the default configuration, the program runs in 
its process along with the kernel debugger, and a new subprocess is created to 
run the main debugger. A new main debugger (and, therefore, a new debugging 
session) is established every time you invoke the debugger. 

In the multiprocess configuration, the program being debugged runs in several 
processes. Each process that is running one or more images under debugger 
control is also running a local copy of the kernel debugger. The main debugger, 
running in a separate subprocess, communicates with the other processes through 
their kernel debuggers. 
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Although all processes of a multiprocess configuration must be in the same 
job, they do not have to be related in a particular process/subprocess hierarchy. 
Moreover, the program images running in separate processes do not have to 
communicate with each other. 

See Section 10.2.9 for system requirements related to multiprocess debugging. 

10.2.2 Specifying Processes in Debugger Commands 

When specifying processes in debugger commands, you can use any of the forms 
listed in Table 10-2, except when specifying processes with the CONNECT 
command (see Section 10.2.4.2). 

The CONNECT command is used to bring a process that is not yet known to 
the debugger under debugger control. Therefore, when specifying a process with 
CONNECT, you can use only its VMS process name or VMS process identification 
number (PID). You cannot use its debugger-assigned process number or any of the 
process built-in symbols (for example, %NEXT_PROCESS) for the process. 


Table 10-2 Process Specifications 


Format 

Usage 

[%PROCESS_NAME] process-name 

The VMS process name, if that name 
contains no spaces or lowercase characters 1 . 

[%PROCESS_NAME] "process-name" 

The VMS process name, if that name 
contains spaces or lowercase characters. 

You can also use apostrophes (') instead of 
quotation marks ("). 

%PROCESS_PID processed 

The VMS process identification number 
(PID, a hexadecimal number). 

%PROCESS_NUMBER process-number 
(or %PROC process-number) 

The number assigned to a process when 
it comes under debugger control. A new 
number is assigned sequentially, starting 
with 1, to each process. If a process 
is terminated with the EXIT or QUIT 
command, the number is not reused diming 
the debugging session. Process numbers 
appear in a SHOW PROCESS display. 
Processes are ordered in a circular list 
so they can be indexed with the built- 
in symbols %PREVTOUS PROCESS and 
%NEXT_PROCESS. 

process-group-name 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to represent a 
group of processes. 

%NEXT_PROCESS 

The next process after the visible process in 
the debugger’s circular process list. 

%PREVIOUSJPROCESS 

The process previous to the visible process in 
the debugger’s circular process list. 

%VISIBLE_PROCESS 

The process whose stack, register set, and 
images are the current context for looking 
up symbols, register values, routine calls, 
breakpoints, and so on. 

1 The process name can include the wildcard character (*). 
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You can omit the %PROCESS_NAME built-in symbol when entering commands. 
For example: 

DBG_2> SHOW PROCESS %PR0C 2, J0NES_3 

You can define a symbol to represent a group of processes (DEFINE/PROCESS_ 
GROUP). This enables you to enter commands in abbreviated form. For example: 

DBG_1> DEFINE/PROCESS_GROUP SERVERS=FILE_SERVER, NETWORK_SERVER 
DBG_1> SHOW PROCESS SERVERS 
Number Name Hold State Current PC 

* 1 FILE_SERVER step FS_PR0G\%LINE 37 

2 NETWORK_SERVER break NET_PR0G\%LINE 24 

DBG_1> 

The built-in symbols %VISIBLE_PROCESS, %NEXT_PROCESS, and 
%PREVIOUS_PROCESS are useful in control structures based on the IF, 
WHILE, or REPEAT commands and in command procedures. 

10.2.3 Monitoring Process Activation and Termination 

By default, a tracepoint is triggered when a process comes under debugger 
control and when it performs an image exit. These predefined tracepoints are 
equivalent to those resulting from entering the SET TRACE/ACTIVATING and 
SET TRACE/TERMINATING commands, respectively. You can set breakpoints 
on these events by means of the SET BREAK/ACTIVATING and SET BREAK 
/TERMINATING commands. 

To cancel the predefined tracepoints, use the CANCEL TRACE/PREDEFINED 
command with the /ACTIVATING and /TERMINATING qualifiers. To cancel any 
user-defined activation and termination breakpoints, use the CANCEL BREAK 
command with the /ACTIVATING and /TERMINATING qualifiers (the /USER 
qualifier is assumed by default when canceling breakpoints or tracepoints). 

The debugger prompt is displayed when the first process comes under debugger 
control. This enables you to enter commands before the main image has started 
execution, as with a one-process program. 

Also, the debugger prompt is displayed when the last process performs an image 
exit. This enables you to enter commands after the program has completed 
execution, as with a one-process program. 

10.2.4 Interrupting the Execution of an Image to Connect It to the Debugger 

You can interrupt a debuggable image that is running without debugger control 
in a process and connect that process to the debugger. 

• To start a new debugging session, use the Ctrl/Y-DEBUG sequence from DCL 
level. 

• To interrupt an image and connect it to an existing debugging session, use 
the CONNECT command. 

10.2.4.1 Using the Ctrl/Y-DEBUG Sequence to Invoke the Debugger 

You use the Ctrl/Y-DEBUG sequence with the multiprocess debugging 
configuration exactly as with the default configuration. That is, run the image 
from DCL level with the RUN/NODEBUG command, then press Ctrl/Y to 
interrupt the image. The DEBUG command causes the debugger to be invoked. 
(See Section 3.1.2.) 
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The following example shows how you might start a new debugging session: 

$ DEFINE/JOB DBG$PR0CESS MULTIPROCESS 
$ RUN/NODEBUG PR0G2 

[ctiWI 

Interrupt 
$ DEBUG 

VAX DEBUG Version 5.5 

SDEBUG-I-INITIAL, language is FORTRAN, module set to SUB4 
predefined trace on activation at SUB4\%LINE 12 in %PR0CESS NUMBER 1 
DBG_1> 

In this example, the DEFINE/JOB command establishes a multiprocess 
debugging configuration. The RUN/NODEBUG command starts the execution of 
image PROG2 without debugger control. The Ctrl/Y-DEBUG sequence interrupts 
execution and invokes the debugger. 

The VAX DEBUG banner indicates that a new debugging session has been 
started. The process-specific prompt (DBG_1>) indicates that this is a 
multiprocess configuration and that execution is suspended in process 1, which is 
running image PROG2. 

The activation tracepoint identifies the location at which execution was 
interrupted (and at which the debugger took control of the process). You can 
also use the SHOW CALLS command to display the call stack at that location. 

After the debugger has been invoked, you can use the CONNECT command to 
bring other processes under debugger control. In the previous example, you could 
use the CONNECT command to bring processes under debugger control that were 
created by PROG2 before you interrupted its execution (see Section 10.2.4.2). 

When using the Ctrl/Y-DEBUG sequence, if a multiprocess debugging session 
already exists in the same job as the image that is interrupted, the image 
connects to that session. In this case, because a new session is not started, 
the VAX DEBUG banner is not displayed when the debugger takes control. This 
situation could occur if, for example, you entered a SPAWN/NOWAIT command 
from the session, started execution with a RUN/NODEBUG command, and then 
entered a Ctrl/Y-DEBUG sequence. 

10.2.4.2 Using the CONNECT Command to Interrupt an Image 

The CONNECT command, used without a parameter, was introduced in 
Section 10.1.5. When used with a parameter, the CONNECT command enables 
you to interrupt a debuggable image that is running without debugger control 
and bring it under control of your current debugging session. 

The image might have been activated as follows: 

• Your program issued a LIB$SPAWN run-time library call or a $CREPRC 
system service call to spawn a process and run an image without debugger 
control 

• You started execution with a RUN/NODEBUG command entered at DCL level 

In the following example, the CONNECT command causes the image running 
in process JONES_3 to be interrupted and to come under control of the current 
debugging session. Process JONES_3 must be in the same job as the session. 

DBG 1> CONNECT JONES 3 
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Note that a process is not identified by a debugger process number until it is 
connected to a debugging session. Therefore, when specifying a process with the 
CONNECT command, you can use only its VMS process name or VMS process 
identification number (PID). 

The effect of the CONNECT command is equivalent to attaching to a process from 
a debugging session and then entering the sequence Ctrl/Y—DEBUG to interrupt 
the running image and invoke the debugger. However, the CONNECT command 
is easier to enter and also enables you to interrupt a process to which you cannot 
attach. 

10.2.5 Screen Mode Features for Multiprocess Debugging 

Screen mode displays, whether predefined or user defined, are associated with 
the visible process by default. For example, SRC shows the source code where 
execution is suspended in the visible process, OUT shows the output of commands 
executed in the context of the visible process, and so on. 

By using the /PROCESS qualifier with the DISPLAY command you can create 
process-specific displays or make existing displays process specific, respectively. 
The contents of a process-specific display are generated and modified in the 
context of that process. You can make any display process specific except for the 
PROMPT display. For example, the following command creates the automatically 
updated source display SRC_3, which shows the source code where execution is 
suspended in process 3: 

DBG 2> DISPLAY/PR0CESS=(%PR0C 3) SRC_3 AT RS23 SOURCE (EXAM/SOURCE .%S0URCE_SC0PE\%PC) 

You assign attributes to process-specific displays as for displays that are not 
process specific. For example, the following command makes display SRC_3 the 
current scrolling and source display—that is, the output of SCROLL, TYPE, and 
EXAMINE/SOURCE commands are then directed at SRC_3: 

DBG 2> SELECT/SCROLL/SOURCE SRC_3 

If you enter a DISPLAY/PROCESS command without specifying a process, the 
specified display is then specific to the process that was the visible process when 
you entered the command. For example, the following command makes OUT_X 
specific to process 2: 

DBG_2> DISPLAY/PROCESS 0UT_X 

The /SUFFIX qualifier appends a process identifying suffix that denotes the 
visible process to a display name. This qualifier can be used directly after a 
display name in any command that specifies a display (for example, DISPLAY, 
EXTRACT, SAVE). It is especially useful within command procedures in 
conjunction with display definitions or key definitions that are bound to display 
definitions. 

In a multiprocess configuration, the predefined tracepoint on process activation 
automatically creates a new source display and a new instruction display for each 
new process that comes under debugger control. The displays have the names 
SRC_n and INST_n, respectively, where n is the process number. These displays 
are initially marked as removed. They are automatically deleted on process 
termination. 

Several predefined keypad key sequences enable you to configure your screen with 
the process-specific source and instruction displays that are created automatically 
when a process is activated. Key sequences that are specific to multiprocess 
programs are as follows: PF1—9, PF4—9, PF4—7, PF4—3, PF4—1. See Section B.5 
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for the general effect of these sequences. Use the SHOW KEY command to 
determine the exact commands. 

10.2.6 Setting Watchpoints in Global Sections 

You can set watchpoints in global sections. A global section is a region of memory 
that is shared among all processes of a multiprocess program. A watchpoint that 
is set on a location in a global section (a global section watchpoint) triggers when 
any process modifies the contents of that location. 

When setting watchpoints on arrays or records, note that performance is 
improved if you specify individual elements rather than the entire structure 
with the SET WATCH command. 

If you set a watchpoint on a location that is not yet mapped to a global section, 
the watchpoint is treated as a conventional static watchpoint. For example: 

DBG_1> SET WATCH ARR(l) 

DBG_1> SHOW WATCH 
watchpoint of PPL3\ARR(1) 

When ARR is subsequently mapped to a global section, the watchpoint is 
automatically treated as a global section watchpoint and an informational 
message is issued. For example: 

DBG_1> GO 

% DEBUG-1-WATVARNOWGBL, watched variable PPL3\ARR(1) has 
been remapped to a global section 

predefined trace on activation at routine PPL3 in %PROCESS_NUMBER 2 
predefined trace on activation at routine PPL3 in ^PROCESS NUMBER 3 
watch of PPL3\ARR(1) at PPL3\%LINE 93 in IPROCESS NUMBER 2 ~ 

93: ARR(l) = INDEX 

old value: 0 
new value: 1 

break at PPL3\%LINE 94 in %PROCESS_NUMBER 2 
94: ARR(I) = I 

After the watched location is mapped to a global section, the watchpoint is visible 
from each process. For example: 

DBG_2> DO (SHOW WATCH) 

For %PROCESS_NUMBER 1 

watchpoint of PPL3\ARR(1) [global-section watchpoint] 

For %PROCESS_NUMBER 2 

watchpoint of PPL3\ARR(1) [global-section watchpoint] 

For %PROCESS_NUMBER 3 

watchpoint of PPL3\ARR(1) [global-section watchpoint] 

10-2.7 Using Multiprocess Commands with the Default Configuration 

All commands, qualifiers, and built-in symbols that are provided for multiprocess 
debugging are also understood in the default debugging configuration and have 
analogous behaviors (where applicable). For example: 

• The EXIT command without a parameter ends a debugging session in both 
configurations. 

• A DO command without the /PROCESS qualifier executes the commands 
specified in all processes. 

• In the default configuration, the visible process is the process that runs the 
entire program. It is identified as process 1 in a SHOW PROCESS display. 

• Process-specific built-in symbols, such as %PROCESS_NUMBER and 
%VISIBLE_PROCESS, are interpreted correctly in the default configuration. 
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This compatibility enables you to use command procedures designed for 
multiprocess debugging when debugging programs that run in only one process. 

10.2.8 Advanced Concepts and Possible Errors 

The debugging configuration (default or multiprocess) is controlled entirely by 
the definition of DBG$PROCESS. If some of the processes in a job have different 
definitions of DBG$PROCESS, the resulting debugging configuration can be very 
confusing. 

The value of DBG$PROCESS is checked when the kernel debugger is first 
invoked. 

Consider the following scenario: 

$ DEFINE/JOB DBG$PR0CESS MULTIPROCESS 
$ RUN TEST 

VAX DEBUG Version 5.5 

DBG_1> SET BREAK/ACTIVATING;GO 

break at program activation in %PROCESS_NUMBER 2 

DBG_2> SHOW PROCESS/ALL 

Number Name Hold State Current PC 

1 SMITH interrupted TEST\%LINE 50 

* 2 SMITHJL activated SUB1\%LINE 71 

DBG_2> SPAWN DEFINE DBG$PROCESS DEFAULT ! Establish a default configuration 
DBG_2> SET BREAK %LINE 100;GO ! Assume that TEST creates a new process 

VAX DEBUG Version 5.5 

break at ILINE 100 in %PROCESS_NUMBER 2 
DBG> SHOW PROCESS/ALL 

Number Name Hold State Current PC 

* 3 SMITH_2 activated MYPROGULINE 10 

DBG_2> SHOW PROCESS/ALL 

Number Name Hold State Current PC 

1 SMITH interrupted TEST\%LINE 50 

* 2 SMITH_1 break SUB1\%LINE 100 

DBG> 

Because of the reassigment of DBG$PROCESS, there are two different main 
debuggers (two debugging sessions) in the job. Both debuggers use the same 
terminal for input and output. Therefore, the prompts and output lines from the 
two sessions are intermixed on the screen. (The effect is similar to what you see 
if you enter a DCL SPAWN/NOWAIT command, in that two processes are sharing 
the terminal.) 

Generally, this mixed default and multiprocess configuration is not desirable. 
However, although potentially confusing, the configuration can be useful if 
you need to debug an experimental copy of a program without disturbing your 
primary debugging session, which has several processes connected to it. In such 
cases, use the SPAWN and ATTACH commands to control the activity of the 
subprocesses. 

10.2.9 System Requirements for Multiprocess Debugging 

Several users debugging multiprocess programs can place a load on a system. 
This section describes the resources used by the debugger, so that you or your 
system manager can tune your system for this activity. 

Note that the discussion covers only the resources used by the debugger. You 
migh t, have to tune your system to support the multiprocess programs themselves. 


10-16 



Debugging Multiprocess Programs 
10.2 Supplemental Information 


10.2.9.1 User Quotas 

Each user needs a PRCLM quota sufficient to create an additional subprocess for 
the debugger, beyond the number of processes needed by the program. 

BYTLM, ENQLM, FILLM, and PGFLQUOTA are pooled quotas. They may need 
to be increased to account for the debugger subprocess as follows: 

• Each user’s ENQLM quota should be increased by at least the number of 
processes being debugged. 

• Each user s PGFLQUOTA might need to be increased. If a user has an 
insufficient PGFLQUOTA, the debugger might fail to activate or cause 
"virtual memory exceeded" errors during execution. 

• Each user s BYTLM and FILLM quotas might need to be increased. The 
debugger requires BYTLM and FILLM quotas sufficient to open each image 
file being debugged, the corresponding source files, and the debugger input, 
output, and log files. The debugger command SET MAX_SOURCE_FILES 
can be used to limit the number of source files kept open by the debugger at 
any one time. 

10.2.9.2 System Resources 

The kernel and main debugger communicate through global sections. The main 
debugger communicates with up to 8 kernel debuggers through a 65-page global 
section. Therefore, the SYSGEN global-page and global-section parameters 
(GBLPAGES and GBLSECTIONS, respectively) might need to be increased. For 
example, if 10 users are using the debugger simultaneously, 10 global sections 
using a total of 650 global pages are required by the debugger. 
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Debugging Vectorized Programs 


This chapter describes features of the debugger that are specific to vectorized 
programs (programs that use VAX vector instructions). Use these features in 
addition to those explained in other chapters. 

The information in this chapter enables you to perform the following tasks: 

Display information about the availability and use of the vector processor on 
your system 

• Control and monitor the execution of vector instructions with breakpoints, 
watchpoints, and so on 

• Examine and deposit into the vector control registers (%VCR, %VLR, and 
%VMR) and the vector registers (%V0 to %V15) 

• Examine and deposit vector instructions and their operands 

• Perform masked operations when examining vector registers or vector 
instructions to display only certain register elements or override the masking 
associated with a vector instruction 

• When using the EXAMINE command, specify composite address expressions 
of a complex form that might be appropriate for a vectorized program 

• Display the decoded results of vector floating-point exceptions 

• Control synchronization between the scalar and vector processors 

• Save and restore the current vector state when using the CALL command to 
execute a routine that might affect the vector state 

• Display vector register data using a screen-mode display 

For additional information that is specific to a vectorized high-level language 
program, see the associated language documentation. For complete information 
about vector instructions and vector registers, see the VAX MACRO and 
Instruction Set Reference Manual. 

-- Notes___ 


1. Compilers do not generate symbol-table data to associate vector 
registers with symbols declared in the program. Therefore, no 
symbolization is available for vector registers during a debugging 
session. Also, you can access a vector register only in scope 0 (the 
scope of the routine at the top of the call stack). 
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2. The examples in this chapter show how to access elements of a 

vector register using array syntax (for example, EXAMINE %V1(37)). 
This syntax is not supported for BLISS. In BLISS, use the SET 
LANGUAGE command to set the language temporarily to some other 
language, such as FORTRAN, then use the array syntax for that 
language. 


11.1 Obtaining Information About the Vector Processor 

The SHOW PROCESS/FULL command provides some information about the 
availability and use of the vector processor on your system. For example: 

DBG> SHOW PROCESS/FULL 


Vector capable: Yes 

Vector consumer: Yes Vector CPU time: 0 00:03:17.18 

Fast Vector context switches: 0 Slow Vector context switches: 


DBG> 

The Vector Capable field can have the following entries: 


Vector-Capable Entry 

Description 

Yes 

The VAX system has a vector processor, and it is available to the 
process that is running the program. 

No (protected) 

The VAX system has a vector processor, but the process running 
the program is denied access to the processor. 

WIEF 

The VAX system does not have a vector processor. It is running 
the VAX Vector Instruction Emulation Facility (WIEF). The 
WIEF is available to the process that is running the program. 

No 

The VAX system does not have an active vector processor, and 
the WIEF is not loaded on the system. 


11.2 Controlling and Monitoring the Execution of Vector 
Instructions 

The following sections explain how to perform the following tasks: 

• Execute the program to (step to) either the next vector instruction or any one 
of a set of specified vector instructions. 

• Set breakpoints and tracepoints that trigger either on any vector instruction 
or on any one of a set of specified vector instructions. 

• Set watchpoints to monitor changes in vector registers. 
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11.2 Controlling and Monitoring the Execution of Vector Instructions 

11.2.1 Executing the Program to the Next Vector Instruction 

To execute the program to the next vector instruction encountered in the program 
enter the STEP/VECTORJNSTRUCTION command. 

You can also execute the program to the next vector instruction whose opcode is 
in a list of opcodes by using the command STEP/INSTRUCTION=(opco<ie/', ... 7). 
For example: 

DBG> STEP/INSTRUCTION=(VLDL,VSTL,MOVL) 

The SET STEP command enables you to change the default unit of execution of 
the STEP command: 

• Enter the SET STEP VECTORJNSTRUCTION command to make the STEP 
command execute the program to the next vector instruction by default. 

• Enter the SET STEP INSTRUCTIONJopcoc/e/, ... 7 ) command to make the 
STEP command execute the program to the next instruction that is in the list 
of opcodes (including a vector instruction) by default. 

11.2.2 Setting Breakpoints and Tracepoints on Vector Instructions 

To set a breakpoint (or a tracepoint) that triggers whenever a vector instruction 
is encountered in the program, enter the SET BREAK/VECTOR_INSTRUCTION 
(or SET TRACE/VECTORJNSTRUCTION) command. 

To cancel such breakpoints or tracepoints, enter the command CANCEL BREAK 
/VECTORJNSTRUCTION or CANCEL TRACE/VECTORJNSTRUCTION. 

You can also set breakpoints and tracepoints on one or more specific vector 
instructions by using the /INSTRUCTION=(opcode/; ... 7 ) qualifier with the SET 
BREAK and SET TRACE commands. For example: 

DBG> SET BREAK/INSTRUCTION 3 (WADDL,WLEQL) 

To cancel such breakpoints and tracepoints, enter the CANCEL BREAK 
/INSTRUCTION or CANCEL TRACE/INSTRUCTION command. 

11.2.3 Setting Watchpoints on Vector Registers 

You can set watchpoints on the vector registers (VO to V15) and on the vector 
control registers (VCR, VLR, and VMR). Section 11.3.1 identifies these registers 
and their built-in debugger symbols. 

These watchpoints are treated like static watchpoints in that, once set, the 
watchpoint is active until you cancel it explicitly. 

In the following example, a watchpoint is set on register VCR: 

DBG> SET WATCH iVCR 

In the case of VMR and VO to V15, you can set a watchpoint either on the 
register aggregate (that is, on all elements of the register), on an individual 
register element, or on a range of elements (a slice). Use the same technique that 
you use to set a watchpoint on an array variable. (See Section 3.6.) 

For example, the following command sets a watchpoint that triggers if any 
element of register V5 changes: 

DBG> SET WATCH %V5 
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The following command sets a watchpoint that triggers if element 37 of V2 
changes (FORTRAN array syntax): 

DBG> SET WATCH %V2(37) 

The following command sets a watchpoint that triggers if any element of V2 in 
the range from element 5 to 13 changes: 

DBG> SET WATCH %V2(5:13) 

11.3 Examining and Depositing into Vector Registers 

The following sections explain how to examine and deposit into the vector control 
registers (VCR, VLR, and VMR) and the vector registers (VO to V15). 

11.3.1 Specifying the Vector Registers and Vector Control Registers 

The VAX architecture provides 16 vector registers (VO to V15) and 3 vector 
control registers (VCR, VLR, VMR). When referencing any of these registers 
in a debugger command, use the following built-in symbols (the register name 
preceded by a percent sign (%)). 


Symbol 

Description 

%V0 ... %V15 

Vector registers (VO ... V15) 

%VCR 

Vector count register (VCR) 

%VLR 

Vector length register (VLR) 

%VMR 

Vector mask register (VMR) 


As with all debugger register symbols, you can omit the percent sign (%) prefix if 
your program has not declared a symbol with the same name. 


11.3.2 Examining and Depositing into the Vector Count Register (VCR) 

The vector count register (VCR) specifies the length of the offset vector generated 
by the IOTA instruction. 

The value of VCR is an integer from 0 to 64. By default, the debugger treats VCR 
as a longword integer. Although you can deposit values greater than 64 into VCR, 
the debugger issues a diagnostic message that the value is out of bounds in such 
cases. 

The following command sequence shows how to manipulate the value of VCR: 

DBG> EXAMINE %VCR 
OUVCR: 8 

DBG> DEPOSIT %VCR = 4 
DBG> EXAMINE %VCR 
0\%VCR: 4 
DBG> 

11.3.3 Examining and Depositing into the Vector Length Register (VLR) 

The vector length register (VLR) limits the highest element of a vector register 
that is processed by a vector instruction. The value of VLR is an integer from 0 
to 64. This value specifies the number of register elements that are processed, 
starting with element 0. 

In the context of a debugging session, the current value of VLR limits the highest 
element of a vector register that you can access with an EXAMINE or DEPOSIT 
debugger command. 
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The following command sequence shows how to manipulate the value of VLR to 
examine different numbers of elements of the vector register VI: 


DBG> EXAMINE 

%VLR 

OUVLR: 4 

DBG> EXAMINE 

%V1 

0\IV1 

(0): 

12 

(1): 

3 

(2): 

138 

(3): 

51 

DBG> DEPOSIT 

%VLR 

DBG> EXAMINE 

%VLR 

OUVLR: 3 

DBG> EXAMINE 

%V1 

0UV1 

(0): 

12 

(1): 

3 

(2): 

138 


DBG> 


You cannot access a register element outside the range from 0 to VLR-1. In the 
following example, the EXAMINE command specifies element 7 of register VI, 
which is out of bounds (FORTRAN array syntax): 


DBG> EXAMINE %VLR 
OUVLR: 3 

DBG> EXAMINE %V1(7) 
%DEBUG-E-VECTSUBRNG, 

DBG> 


vector register subscript out of bounds, 
bounds are 0..2 


By default, the debugger treats VLR as a longword integer. Although you can 
deposit values greater than 64 into VLR, the debugger issues a diagnostic 
message that the value is out of bounds in such cases. 

11.3.4 Examining and Depositing into the Vector Mask Register (VMR) 

The vector mask register (VMR) specifies a mask (a bit pattern) that a vector 
instruction uses in order to operate on only certain elements of a vector register 
operand. A masked vector instruction cannot operate on an element of a vector 
register that is masked by VMR. 

VMR has 64 bits (1 quadword), numbered 0 to 63. Each bit corresponds to an 
element of a vector register. The value of a particular bit (0 or 1) determines 
whether the corresponding register element is operated on during a masked 
operation. 

Masked operations are explained in Section 11.4.1 and Section 11.5. This section 
describes only how to display and change the value of VMR. 

To examine one or more specific elements (bits) of VMR, use the same technique 
that you use to examine an array variable. (See Section 4.2.3.) 

For example, the output of the following command shows that bit 5 of VMR is set 
(FORTRAN array syntax): 

DBG> EXAMINE IVMR(5) 

0UVMR(5): 1 

DBG> 


11-5 











Debugging Vectorized Programs 

11.3 Examining and Depositing into Vector Registers 


The following command displays the values of bits 4 to 6 of VMR. Bits 4 and 5 
are set, and bit 6 is clear: 

DBG> EXAMINE %VMR(4:6) 

0\%VMR 

(4) : 1 

(5) : 1 

( 6 ) : 0 

DBG> 

By default, when you examine VMR without specifying subscripts, the debugger 
displays the value of the register as a quadword integer in hexadecimal format, 
to reduce the size of the output display. For example: 

DBG> EXAMINE %VMR 
0\%VMR 

(0): OFFFFFFF FFFFFFFF 

DBG> 

By specifying the EXAMINE/BIN %VMR or EXAMINE %VMR(0:63) command, 
you can display the value of each bit of VMR in a 64-row array format. 

As with an array variable, you can deposit a value into one bit of VMR at a time. 
For example: 

DBG> EXAMINE %VMR(37) 

0\%VMR(37): 1 

DBG> DEPOSIT %VMR(37) = 0 
DBG> EXAMINE IVMR(37) 

0\%VMR(37): 0 

DBG> 

You can also deposit a quadword integer value into the entire aggregate by using 
the DEPOSIT/QUADWORD command. For example: 

DBG> DEPOSIT/QUADWORD %VMR = %HEX OFFFFF 

DBG> EXAMINE %VMR 

0\%VMR 

(0): 00000000 00OFFFFF 

DBG> 

When specifying an element of VMR in a language expression, remember that 
VMR is an array of bits. You might have to temporarily set the language to one 
that allows bit operations, such as C or BLISS. For example: 

DBG> SET LANGUAGE C 
DBG> DEFINE/VALUE K = 0 

DBG> FOR 1=0 TO 63 DO (IF %VMR[I] == 1 THEN (DEF/VAL K = K + 1)) 

11.3.5 Examining and Depositing into the Vector Registers (VO to VI5) 

There are 16 vector registers, designated VO to V15. Each of the vector registers 
has 64 elements, numbered 0 to 63, and each element has 64 bits (one quadword). 

To examine one or more elements of a vector register, use the same technique 
that you use to examine an array variable. (See Section 4.2.3.) The examples in 
this section use FORTRAN array syntax: 

DBG> EXAMINE %V3 (Examine all elements of V3 

DBG> EXAMINE %V3(27) (Examine element 27 of V3 

DBG> EXAMINE %V3(3:14) (Examine elements 3 to 14 of V3 

DBG> EXAMINE %V0(2),%V3(1:4) (Examine element 2 of V0 and 

(elements 1 to 4 of V3 


11-6 















Debugging Vectorized Programs 
11.3 Examining and Depositing into Vector Registers 

The values of register elements are displayed in an indexed format similar to that 
used for an array variable. For example, the following command displays the 
values of elements 1 to 3 of register VI: 

DBG> EXAMINE %V1(1:3) 

0UV1 

(1) : 3 

(2) : 138 

(3) : 51 

DBG> 

Note that you cannot examine a range of vector registers. For example, the 
following commands are invalid: 

DBG> EXAMINE %V0:%V3 
DBG> EXAMINE %V2(7):%V3(12) 

As with an array variable, you can deposit a value into only one element of 
a vector register at a time. For example, the following command deposits the 
integer value 8531 into element 9 of VO: 

DBG> DEPOSIT %V0(9) = 8531 

The current value of the vector length register (VLR) limits the highest register 
element that you can examine or deposit into. (See Section 11.3.3.) Therefore, the 
following commands are equivalent: 

DBG> EXAMINE %V1 

DBG> EXAMINE %V1(0:%VLR-1) 

The expression 0:%VLR—1 specifies the range of register elements that are 
denoted by the current value of VLR. 

By default, the debugger treats each element of a vector register as a longword 
integer and displays the value in the current radix. For example: 

DBG> EXAMINE %V3(27) 

0\%V3(27): 5983 

DBG> DEPOSIT %V3(27) = 3625 
DBG> EXAMINE %V3(27) 

0\%V3(27): 3625 

DBG> 

However, note that a register value that is examined in the context of a vector 
instruction (that is, as an instruction operand) is displayed in the data type that 
is appropriate for the instruction. (See Section 11.4.1.) 

To display the lull (quadword) value of an element of a vector register as a 
quadword integer, use the EXAMINE/QUADWORD command. Similarly, to 
deposit a quadword integer value into a register element, use the command 
DEPOSIT/QUADWORD. 

You can also use any of the other type qualifiers associated with the EXAMINE 
and DEPOSIT commands (for example, /FLOAT) to override the default type. For 
example: 

DBG> EXAMINE %V5(2) 

0\%V5(2): 0 

DBG> EXAMINE/D_FLOAT %V5(2) 

0\%V5(2): 0.0000000000000000 

DBG> 
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You can use register symbols in language expressions, subject to the restrictions 
on using aggregate data structures in language expressions. (See Section 4.1.5.1.) 
For example, the following expression is valid (FORTRAN syntax): 

DBG> EVALUATE %V0(4) .EQ. %V1(4) 

However, the following expression is not valid because more than one register 
element is specified: 

DBG> EVALUATE %V0 .EQ. %V1 

11.4 Examining and Depositing Vector Instructions 

The techniques for manipulating vector instructions include all of those used for 
scalar instructions (described in Section 4.3) and additional techniques specific to 
vector instructions: 

• You can use a screen-mode instruction display to present the scalar and 
vector instructions decoded from the instruction stream of your program. 

• You can execute your program at the vector instruction level by using 
commands such as the following: 

STEP/VECTORJNSTRUCTION 
STEP/INSTRUCTION =(opcode[, ... D 
SET STEP VECTORJNSTRUCTION 
SET STEP INSTRUCTION =(opcode[, ... 7) 

SET BREAK/VE CTOR_IN STRU CTION 
SET BREAK/INSTRUCTION=(opcocfe7, ... 7 ) 

• You can use the EXAMINE/OPERANDS command to display the instruction 
at the current PC value, including any operand information contained in 
vector registers. In addition, the qualifiers /TMASK and /FMASK enable 
you to simulate the effect of the vector mask register (VMR) or override any 
masking associated with the examined instruction so that you can hide or 
display specific register elements. 

• You can deposit a vector instruction at a particular memory address in your 
program. 

Whether you are examini n g or depositing vector instructions, the debugger 
correctly processes the vector instruction qualifiers according to the instructions 
to which they apply. The following table summarizes the functions of these 
qualifiers. See the VAX MACRO and Instruction Set Reference Manual for 
complete information about their use. 


Instruction 

Qualifier Description _ 

/U Enable floating underflow (vector floating-point instructions) 

/V Enable integer overflow (vector integer instructions) 

/M Modify intent (VLDx and VGATHx instructions) 

/0 Perform masked operations only on elements for which the VMR bit is 0 

/I Perform masked operations only on elements for which the VMR bit is 1 
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11.4.1 Examining Vector Instructions and Their Operands 

When you examine a program location that contains a vector instruction, the 
debugger decodes that instruction and translates it and its operands into 
their VAX MACRO assembler form, with the following restrictions. (See the 
VAX MACRO and Instruction Set Reference Manual for details about instruction 
opcodes.) 

• If the vector control word is not encoded using either immediate or short- 
literal mode, the debugger cannot translate the opcode and, therefore, 
displays the instruction and its operands in their VAX vector architectural 
form rather than their VAX MACRO assembler form. 

• If the VAX opcode is VSMERGEx, the debugger displays the instruction 
mnemonic as VSMERGE rather than VSMERGEF, VSMERGED, or 
VSMERGEG. In this case, a literal src.rq operand is displayed as a quadword 
integer in the current radix. 

The command EX/ MINE/OPERANDS .%PC enables you to display the 
instruction at the current PC value and its operands. (See Section 4.3.1.) When 
you examine a vector instruction with this command, the values of any vector 
register operands are displayed as for an array variable. For example (FORTRAN 
array syntax): 

DBG> EXAMINE/OPERANDS .IPC 

PROG$MAIN\%LINE 81+19: VSTL V0,W A -572(FP),S A #4 

VO contains: 

0\%V0(0): 137445504 

0\%V0(1): 137445504 

0\%V0(2): 137445504 

W A -572(FP) 2145991456 contains 2 

DBG> 

As with scalar instructions, operand values are displayed in the data type that is 
appropriate for the examined instruction. 

When you use the EXAMINE/OPERANDS command, the display of register 
elements depends on the following factors: 

• The current value of VLR. The highest element of a vector register that is 
operated on (and, therefore, displayed) is limited by the value of VLR. 

• Whether the examined instruction is performing a masked operation. In 
an unmasked operation, all register elements (up to VLR-1) are displayed. 

A masked operation is indicated by the presence of the /I or /0 instruction 
qualifier. For example: 

WADDF/1 VO, VI, V2 

In a masked operation, only the elements that correspond to the set or clear 
bits of VMR are operated on (depending on whether the instruction qualifier 
is /I or /0, respectively). 

These concepts are illustrated in the following two examples, which show an 
unmasked and a masked register-to-register operation, respectively. 

In the next example, the examined instruction, VVADDF, is performing an 
unmasked operation so that the current value of VMR is irrelevant. All elements 
from 0 to 5 are displayed: 


11-9 









Debugging Vectorized Programs 

11.4 Examining and Depositing Vector Instructions 


DBG> EXAMINE %VLR 
0\%VLR: 6 

DBG> EXAMINE %VMR(0:5) 

0\%VMR 

( 0 ): 1 

( 1 ): 0 

( 2 ): 1 

(3) : 0 

(4) : 1 

(5) : 0 

DBG> EXAMINE/OPERANDS .%PC 
PROG$MAIN\%LINE 12: WADDF V0,V1,V2 


VO 

contains: 



0\%V0(0): 

7.0000000 


0\%V0(1): 

7.0000000 


0\%V0(5): 

7.0000000 

VI 

contains: 



0\m(0): 

4.0000000 


0\%V1(1): 

4.0000000 


0\%V1(5): 

4.0000000 

V2 

contains: 



0\%V2(0): 

5.0000000 


0\%V2(1): 

5.0000000 


0\%V2 (5): 

5.0000000 


DBG> 

In the next example, the same WADDF instruction is performing a masked 
operation. The instruction qualifier /I specifies that elements that match the set 
bits (bit value 1) in VMR are operated on: 

DBG> EXAMINE %VLR 
0\%VLR: 6 

DBG> EXAMINE %VMR(0:5) 

0\%VMR 

(0): 1 

( 1 ): 0 

( 2 ): 1 

(3) : 0 

(4) : 1 

(5) : 0 

DBG> EXAMINE/OPERANDS .%PC 
PROG$MAIN\%LINE 12: WADDF/1 V0,V1,V2 

VO contains: 

0\%V0(0): 7.0000000 

0\%V0(2): 7.0000000 

0\%V0(4): 7.0000000 

VI contains: 

0\%V0(0): 4.0000000 

0\%V0(2): 4.0000000 

0\%V0(4): 4.0000000 

V2 contains: 

0\%V0(0): 5.0000000 

0\%V0(2): 5.0000000 

0\%V0(4): 5.0000000 

DBG> 
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The next example shows a masked operation that loads data from memory to a 
vector register. Comments, keyed to the callouts, follow the example. 

DBG> EXAMINE %VLR 
0\%VLR: 6 

DBG> EXAMINE %VMR(0:5) 

OXIVMR 

( 0 ): 1 

( 1 ): 0 

( 2 ): 1 

(3) : 0 

(4) : 1 

(5) : 0 

DBG> EXAMINE/OPERANDS .%PC O 

PROG$MAIN\%LINE 31+12: VLDL/1 ARR+8,#4,V0 0 

PROG$MAIN\ARR(3) (address 1024) contains 35 0 

VO contains: 

0\%V0(0): 0 0 

0\%V0(2): 0 

0\%V0(4): 0 

DBG> EXAMINE ARR(1:8) 0 

PROG$MAIN\ARR 


(1): 

9 

(2): 

17 

(3): 

35 

(4): 

73 

(5): 

81 

(6): 

6 

(7): 

7 

(8): 

49 


DBG> 

The comments that follow refer to the callouts in the previous example: 

0 The EXAMINE/OPERANDS command shows that a VLDL instruction is 
about to be executed. The instruction will load longword-integer data from 
array ARR, starting at ARR+8 bytes, into register VO, as illustrated in 
Figure 11—1. Figure 11—1 shows the contents of VO after the instruction 
has been executed. Note that array ARR is indexed 1 to n, not 0 to n-1 
(FORTRAN example). 

0 The stride value (#4) of the VLDL instruction specifies the number of bytes 
between the start addresses of array elements. 

0 The instruction operand ARR+8 denotes the start of array element 3, ARR(3). 
The EXAMINE/OPERANDS command displays only the first element of array 
ARR that is operated upon (see item 0). 

© The current values of VLR and VMR will cause the VLDL instruction to load 
the contents of array elements ARR(3), ARR(5), and ARR(7) into register 
elements V0(0), V0(2), and V0(4), respectively. The EXAMINE/OPERANDS 
command shows the contents of VO before the instruction has been executed. 

0 For reference, the EXAMINE ARR(1:8) command displays the full range of 
array elements that are associated with the load operation. 
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Figure 11-1 

Instruction: 


Masked Loading of Array Elements from Memory into a Vector 
Register 

VLDL/l ARR+8,#4,VO 
ARR 



ZK-1937A-GE 


11.4.2 Depositing Vector Instructions 

The techniques for depositing VAX scalar instructions also apply to depositing 

vector instructions. (See Section 4.3.2.) For example, the following command 

deposits a masked WMULF vector instruction at the current PC address: 

DBG> DEPOSIT/INSTRUCTION .%PC = "WMULF/0 V2,V3,V7" 

Note the following additional information when depositing vector instructions. 

(See the VAX MACRO and Instruction Set Reference Manual for details about 

instruction opcodes.) 

• The regnum.rw operand of the MxVP and VSYNC instructions is generated as 
a short literal. 

• Do not specify a vector control word when depositing a vector instruction. 

The debugger constructs the vector control word based on the instruction and 
instruction qualifiers, if any, and encodes it using immediate mode. 

• The value of an immediate argument of a VSMERGEx instruction is 
interpreted according to the data type associated with that instruction. 

For example, the src argument for a VSMERGEF instruction is interpreted 
as a F_floating value, and so on. For VSMERGE without a type suffix, the 
debugger interprets a literal src operand as a quadword integer in the current 
radix. 
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11.5 Using a Mask When Examining Vector Registers or 
Instructions 

Section 11.4.1 explains how the command EXAMINE/OPERANDS ,%PC displays 
vector instruction operands, depending on whether or not the operation is masked 
by VMR. 

This section explains how to specify an arbitrary mask in order to simulate or 
override the effect of VMR and obtain the following results: 

• Display only certain elements of a vector register or of an array in memory 

• Override the operand masking (if any) that might be associated with an 
examined instruction 

You specify a mask by using the /TMASK or /FMASK qualifier with the 
EXAMINE command. 


—- Note_ 

The remainder of this section describes use of the /TMASK and /FMASK 
qualifiers when examining vector registers. Unless indicated otherwise, 
the discussion also applies to use of these qualifiers when examining 
memory arrays. 


The /TMASK qualifier applies the EXAMINE command only to the elements of 
the examined register that correspond to the set bits (bit value: 1) of the mask. 
The /FMASK qualifier applies the EXAMINE command only to the elements that 
correspond to the clear bits (bit value: 0) of the mask. 

The current value of VLR limits the highest element of a vector register that 
you can examine. But the value of VLR does not affect examining an array in 
memory. 

You can optionally specify a mask (in the form of a mask address expression) with 
the /TMASK and /FMASK qualifiers: 

• Section 11.5.1 describes use of these qualifiers with the default mask, which 
is VMR. 

• Section 11.5.2 describes use of these qualifiers with some arbitrary slice of 
VMR as the mask. 

• Section 11.5.3 describes use of these qualifiers with a mask other than VMR. 

11.5.1 Using VMR as the Default Mask 

By default, if you do not specify a mask with the EXAMINE/TMASK or 
EXAMINE/FMASK command, VMR is used as the mask. That is, the EXAMINE 
command is applied only to the elements of the vector register that correspond to 
the set bits (in the case of /TMASK) or clear bits (in the case of/FMASK) of VMR. 

In the examples that follow, VLR has the value 6 and VMR(0:VLR-1) has the 
following set of values: 
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DBG> EXAMINE %VMR(0:%VLR-1) 

0\%VMR 

( 0 ): 1 

( 1 ): 0 

( 2 ): 1 

(3) : 0 

(4) : 1 

(5) : 0 

DBG> 

The following command displays the value of V3 without using a mask. All 
elements of V3 from 0 to VLR-1 are displayed: 

DBG> EXAMINE %V3 
0\%V3 


(0): 

17 

(1): 

138 

(2): 

3 

(3): 

9 

(4): 

51 

(5): 

252 


DBG> 

The following command displays the elements of V3 (in the range from 0 to 
VLR-1) for which VMR(i) has the value 1: 

DBG> EXAMINE/TMASK %V3 
0\%V3 

(0): 17 

(2) : 3 

(4) : 51 

DBG> 

The following command displays the elements of V3 (in the range from 0 to 
VLR-1) for which VMR(i) has the value 0: 

DBG> EXAMINE/FMASK %V3 
0\%V3 

(1): 138 

(3) : 9 

(5) : 252 

DBG> 

In the following example, the /FMASK qualifier is used when examining an 
instruction and its vector-register operands. The EXAMINE/OPERANDS/FMASK 
command displays the register-operand elements (in the range from 0 to VLR-1) 
for which VMR(i) has the value 0: 

DBG> EXAMINE/OPERANDS/FMASK .%PC 
PROG$MAIN\%LINE 341+16: WEQLL V0,V1 
VO contains: 

0\%V0(1): 0 

0\%V0(3): 0 

0\%V0(5): 0 

VI contains: 

0\%V1(1): 0 

0\%V1(3): 0 

0\%V1(5): 0 

DBG> 
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11.5.2 Using a Slice of VMR as the Mask 

If you specify a slice of VMR with the EXAMINE/TMASK or EXAMINE/FMASK 
command, the output is displayed according to the following conventions: 

1. The number of mask elements specified limits the number of register element 
that you can examine. For example: 

DBG> EXAMINE %VLR 
0\%VLR: 12 

DBG> EXAMINE %VMR(3:5) 

0\%VMR 

(3) : 1 

(4) : 1 

(5) : 1 

DBG> EXAMINE/TMASK=(%VMR(3:5)) %V0(3:10) 

0\IV0 

(3) : 9 

(4) : 51 

(5) : 252 

DBG> 

Note the use of parentheses when specifying a mask with the /TMASK 
qualifier. 

2. The lowest specified element of the mask is applied to the lowest specified 
element of the register. For example, EXAMINE/TMASK %V0(4:7) applies 
VMR(O) to V0(4), VMR(l) to V0(5), and so on. If the lowest specified elements 
of the mask and register do not match, the debugger lists both the mask 
elements and the register elements that are operated on and issues a 
message. For example: 

DBG> EXAMINE %VLR 
0\%VLR: 12 

DBG> EXAMINE %VMR(4:7) 

0\%VMR 

(4) : 1 

(5) : 0 

( 6 ) : 1 

(7): 1 

DBG> EXAMINE/TMASK=(%VMR(4:7)) %V0(3:10) 

%DEBUG-I-MASKMISMATCH, mask/target subscripts do not match, 

displaying mask 

0\%V0 

%VMR(4): 1 

%V0(3): 9 

%VMR(6): 1 

%V0(5): 252 

%VMR(7): 1 

%V0(6): 56 

DBG> 

11.5.3 Using a Mask Other Than VMR 

If you specify a mask address expression other than VMR with the EXAMINE 
/TMASK or EXAMINE/FMASK command, the value at that address is used as 
the mask, subject to the following conventions: 

• If the mask address expression denotes a Boolean array, its values are used 
as the mask in the same basic way that VMR is used in the default case. In 
the following example, BOOL_ARR, a 4-element Boolean array variable, is 
used as the mask: 
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DBG> EXAMINE 4VLR 
0\%VLR: 6 

DBG> EXAMINE B00L_ARR 
PROG$MAIN\BOOL_ARR 
( 0 ): 0 

( 1 ): 0 

( 2 ): 1 

(3): 0 

DBG> EXAMINE/FMASK=(B00L_ARR) 4V0 

4DEBUG-I-MASKN0TVMR, mask used is not %VMR, displaying 
specified mask 

OUVO 

BOOL_ARR(0): 0 

%V0(0): 17 

BOOL_ARR(l): 0 

%V0(1): 138 

BOOL_ARR(3): 0 

%V0(3): 9 

DBG> 

As shown in the example, when you use a mask other than VMR, the 
debugger displays both the mask elements and the register elements that are 
operated on and issues a message. 

• If the mask address expression denotes a non-Boolean array, the least 
significant bit of each array element is used as the mask for the corresponding 
element of the register. 

• If the mask address expression denotes a Boolean scalar type, its value is 
used as the mask for the first element of the register. No other elements are 
examined. In the following example, BOOL_VAR, a single-element Boolean 
variable, is used as the mask: 

DBG> EXAMINE BOOL_VAR 

PROG$MAIN\BOOL_VAR: 1 

DBG> EXAMINE/TMASK=(BOOL_VAR) 4V0 

% DEBUG-1-MASKNOTVMR, mask used is not 4VMR, displaying 
specified mask 

0\%V0 

BOOL_VAR: 1 

%V0(0): 17 

DBG> 

• If the mask address expression denotes any other type, its least significant 
bit value is used as the mask for the first element of the register. No other 
elements are examined. 

• The number of mask elements specified limits the number of register elements 
that you earn examine, as when the mask is VMR (see Section 11.5.2). 

• For a multielement mask, the lowest specified element of the mask is applied 
to the lowest specified element of the register, as when the mask is VMR (see 
Section 11.5.2). 

11.6 Examining Composite Vector Address Expressions 

When using the EXAMINE command, you can specify various forms of composite 
address expressions—expressions that include byte offsets from a given address. 
For example, if X is an integer variable, the following EXAMINE command 
displays the value currently stored at the memory location that is 6 bytes beyond 
the address of X: 
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DBG> EXAMINE X + 6 
MOD3\X+6: 274903 
DBG> 


The examples in this section show how to specify composite address expressions 
of a form that might be appropriate for a vectorized program. 

The next example shows how you might verify the effect of a VSCATL instruction. 
The instructions shown are decoded from a FORTRAN program. Comments, 
keyed to the callouts, follow the example. 

DBG> EXAMINE %VLR 
0\%VLR: 5 

DBG> EXAMINE/OPERANDS .%PC O 
PR0G1$MAIN\%LINE 9+32: VSCATL V7,W A -804(Rll),V9 
V7 contains: 


0\%V7(0): 

11 

0\%V7(1): 

13 

0\%V7(2): 

15 

0\%V7(3): 

17 

0\%V7(4): 

19 


W A -804(R11)PR0G1$MAIN\ARRX(1) (address 1820) contains 0 © 

V9 contains: 


0\%V9(0): 

0 

0\%V9(1): 

8 

0\%V9(2): 

16 

0\%V9(3): 

24 

0\%V9(4): 

32 


DBG> SHOW SYMBOL/TYPE ARRX © 
data PR0G1$MAIN\ARRX 

array descriptor type, 1 dimension, bounds: [1:200], size: 800 bytes 

cell type: atomic type, longword integer, size: 4 bytes 
DBG> EXAMINE ARRX(l) + . %V9 (0: WLR-1) © 

PR0G1$MAIN\ARRX(1): 0 

PR0G1$MAIN\ARRX(3): 0 

PR0G1$MAIN\ARRX(5): 0 

PR0G1$MAIN\ARRX(7): 0 

PROGl$MAIN\ARRX(9): 0 

DBG> STEP/INSTRUCTION © 

stepped to PR0G1$MAIN\%LINE 9+40: MOVZBL I A #64,AP 
DBG> EXAMINE ARRX(l) + .%V9(0:%VLR-1) © 

PR0G1$MAIN\ARRX(1): 11 

PR0G1$MAIN\ARRX(3): 13 

PR0G1$MAIN\ARRX(5): 15 

PR0G1$MAIN\ARRX(7): 17 

PR0G1$MAIN\ARRX(9): 19 

DBG> 


The comments that follow refer to the callouts in the previous example: 

O The EXAMINE/OPERANDS command shows that a VSCATL instruction is 
about to be executed. The instruction will transfer longword-integer (4-byte) 
data from register V7 into memory locations. These locations are determined 
by adding offset values, contained in register V9, to a base address. 

© Register V7 contains the longword-integer values to be transferred to memory. 

© The base address specified as an operand to the VSCATL instruction is 
symbolized as ARRX(1), which denotes element 1 of array ARRX. 

© Register V9 contains the offset from the base address, in bytes, of each target 
vector element in memory. 

© The SHOW SYMBOL/TYPE command indicates that ARRX is an array of 
contiguous longword integers. 
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0 The EXAMINE command displays the values of the target vector elements in 
memory. The address expression specified uses the offset values contained in 
register V9 to set the start address of successive vector elements in memory, 
relative to ARRX(1), the base address. The debugger symbolizes the locations 
of vector elements in memory in terms of the elements of array ARRX. In 
this example, vector elements begin every 8 bytes, coinciding with every other 
element of array ARRX. Because the VSCATL instruction has not yet been 
executed, all of the vector elements in memory contain the value zero. 

Q The STEP/INSTRUCTION command executes the VSCATL instruction and 
suspends execution at the next instruction, MOVZBL. 

© As in item 0, the EXAMINE command displays the values of the target 
vector elements in memory. Now the contents of memory show that the 
values have been transferred from register V7. 

The next example shows how to specify a more complex vector address expression 
with the EXAMINE command. 

Assume that array ARRZ has contiguous quadword-integer (8-byte) elements. 

The fourth EXAMINE command in the example displays the values of vector 
elements in memory, starting at element ARRZ(l). As in the previous example, 
the debugger symbolizes the locations of vector elements in terms of the array 
elements. The location of successive vector elements relative to ARRZ(l) is 
computed by adding the values contained in registers VI and V3 to specify a 
combined offset for a particular element. The order in which vector elements are 
displayed is determined by cycling through all the values in the last specified 
register (V3(0:2)) for each value in the first specified register (VI). In this 
example, the values of all vector elements are zero. 


DBG> EXAMINE %VLR 
0\%VLR: 4 
DBG> EXAMINE %V1 
0\%V1 

( 0 ): 0 

( 1 ) : 4 

( 2 ) : 8 

(3): 12 

DBG> EXAMINE %V3 
0\%V1 

( 0 ): 0 

( 1 ): 8 

( 2 ): 16 

(3): 24 

DBG> EXAMINE ARRZ(l) + 
PROG4$MAIN\ARRZ(1): 
PR0G4$MAIN\ARRZ(2): 
PR0G4$MAIN\ARRZ(3): 
PROG4$MAIN\ARRZ(1)+4: 
PR0G4$MAIN\ARRZ(2)+4: 
PROG4$MAIN\ARRZ(3)+4: 
PROG4$MAIN\ARRZ(2): 
PROG4$MAIN\ARRZ(3): 
PROG4$MAIN\ARRZ(4): 
PROG4$MAIN\ARRZ(2)+4: 
PR0G4$MAIN\ARRZ(3)+4: 
PR0G4$MAIN\ARRZ(4)+4: 
DBG> 


.%V1(0:3) 
0 ! 

0 ! 

0 ! 

0 ! 

0 ! 

0 ! 

0 ! 

0 ! 

0 ! 

0 ! 

0 ! 

0 ! 


+ .%V3(0:2) 
ARRZ(1)+0+0 
ARRZ(1)+0+8 
ARRZ(1)+0+16 
ARRZ(1)+4+0 
ARRZ(1)+4+8 
ARRZ(1)+4+16 
ARRZ(1)+8+0 
ARRZ(1)+8+8 
ARRZ(1)+8+16 
ARRZ(1)+12+0 
ARRZ(1)+12+8 
ARRZ(1)+12+16 
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11.7 Displaying the Results of Vector Floating-Point Exceptions 

When a vector instruction causes a floating-point exception in a vector element, 
the exception result is encoded into the corresponding element of the destination 
register. 

In such cases, you can use the EXAMINE/FLOAT command to display the 
decoded exception message in the associated register element. This technique 
enables you to identify a floating-point exception that is still pending delivery, as 
illustrated in Section 11.8. The following example shows that a vector instruction 
caused a floating divide-by-zero exception in element 2 of register V5: 

DBG> EXAMINE/FLOAT IV5 
0\%V5 

(0): 297.2800 

(1) : 87.41499 

(2) : Reserved operand, encoded as floating divide by zero 

(3) : 173.8650 

DBG> 

If the program copies values from vector registers into memory, you can apply 
the EXAMINE/FLOAT command to the memory location and display the decoded 
information, as you would for a vector register. 

The following table identifies the decoded debugger message for each type of 
vector floating-point exception. 


Exception Debugger Message 

Floating underflow Reserved operand, encoded as floating underflow 

Floating divide by zero Reserved operand, encoded as floating divide by zero 

Floating reserved operand Reserved operand, encoded as floating reserved operand 

Floating overflow Reserved operand, encoded as floating overflow 


11.8 Controlling Scalar-Vector Synchronization 

To achieve high performance, the VAX scalar and vector processors operate 
concurrently as much as possible. The scalar processor passes any vector 
instructions to the vector processor and then continues executing scalar 
instructions while the vector processor executes vector instructions. 

In some cases, the operation of the two processors must be synchronized to ensure 
correct program results. By using synchronizing instructions such as SYNC, 
MSYNC, and VSYNC, the program forces certain operations to complete before 
others are initiated. See the VAX MACRO and Instruction Set Reference Manual 
for more information about these instructions and scalar-vector synchronization. 

If the program has been vectorized by the compiler (for example, the VAX 
FORTRAN compiler), the necessary synchronizing instructions are automatically 
generated. However, VAX MACRO programmers need to code synchronizing 
instructions explicitly. 

By default, the debugger does not force scalar-vector synchronization during 
program execution except for its own internal purposes. The program executes 
as if it were running without debugger control, and synchronization is controlled 
entirely by the program. This default mode of operation is established by the 
SET VECTORJMODE NOSYNCHRONIZED command. 
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When you use the debugger in the default, nonsynchronized vector mode, certain 
vector operations might be in an interrupted state when program execution is 
suspended at a breakpoint, watchpoint, or at the completion of a STEP command. 
For example: 

• An exception caused by a vector instruction might be pending delivery. 

• An operation that transfers data between vector registers and scalar memory 
might not have completed. Therefore, examining the contents of memory or 
vector registers might yield unpredictable results. 


To eliminate potential confusion in such cases, enter the command 
SYNCHRONIZE VECTOR_MODE. It forces immediate synchronization between 
the scalar and vector processors. Entering this command is equivalent to issuing 
a SYNC and an MSYNC instruction at the location in the program at which 
execution is suspended. The effect is as follows: 

• Any exception that was caused by a vector instruction and was still pending 
delivery is immediately delivered. Note that forcing the delivery of a pending 
exception triggers an exception breakpoint or tracepoint (if one was set) 
or invokes an exception handler (if one is available at that location in the 
program). 


• Any read or write operation between vector registers and either the general 
registers or memory is completed immediately—that is, any vector memory 
instruction that was still being executed completes execution. 


The following MACRO example shows the effect of the SYNCHRONIZE 
VECTOR_MODE command. Comments, keyed to the callouts, follow the 
example. 

DBG> STEP O 

stepped to .MAIN.\SUB\%LINE 99 
99: WDIVD V1,V0,V2 

DBG> STEP © 

stepped to .MAIN.\SUB\%LINE 100 
100: CLRL R0 

DBG> EXAMINE/FLOAT IV2 © 

0\%V2 

[0]: 13.53400 

[1] : Reserved operand, encoded as floating divide by zero 

[2] : 247.2450 


DBG> SYNCHRONIZE VECT0R_M0DE © 

%SYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, 
mask=00000004, PC=000002E1, PSL=03C00010 

break on unhandled exception preceding .MAIN.\SUB\%LINE 100 
100: CLRL R0 

DBG> 

The comments that follow refer to the callouts in the previous example: 

O This STEP command suspends program execution on line 99, just before 
a WDIVD instruction is executed. Assume that, in this example, the 
instruction will trigger a floating-point divide-by-zero exception. 

© This STEP command executes the WDIVD instruction. Note, however, that 
the exception is not delivered at this point in the execution of the program. 
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© The EXAMINE/FLOAT command displays a decoded exception message in 
element 1 of the destination register, V2 (see Section 11.7). This confirms 
that a floating-point divide-by-zero exception was triggered and is pending 
delivery. 

© The SYNCHRONIZE VECTOR_MODE command forces the immediate 
delivery of the pending vector exception. (Note that you might obtain a 
different set of diagnostic messages if your program were using the WIEF 
rather than vector processor hardware.) 

An alternative to using the SYNCHRONIZE VECTOR.MODE command is to 
operate the debugger in the synchronized vector mode by entering the SET 
VECTOR_MODE SYNCHRONIZED command. This command causes the 
debugger to force automatic synchronization between the scalar and vector 
processors whenever a vector instruction is executed. Specifically, the debugger 
issues a SYNC instruction after every vector instruction and, in addition, an 
MSYNC instruction after any vector instruction that accesses memory. This 
forces the completion of all activities associated with the vector instruction that is 
being synchronized: 

• Any exception that was caused by a vector instruction is delivered before 
the next scalar instruction is executed. Note that forcing the delivery of a 
pending exception triggers an exception breakpoint or tracepoint (if one was 
set) or invokes an exception handler (if one is available at that location in the 
program). 

• Any read or write operation between vector registers and either the general 
registers or memory is completed before the next scalar instruction is 
executed. 

The following example shows the effect of the SET VECTOR_MODE 
SYNCHRONIZED command on the same instruction stream that was used 
in the previous example. Comments, keyed to the callouts, follow the example. 

DBG> SHOW VECTOR_MODE 

Vector mode is nonsynchronized 

DBG> SET VECTOR_MODE SYNCHRONIZED O 

DBG> SHOW VECTOR_MODE 

Vector mode is synchronized 

DBG> STEP © 

stepped to .MAIN.\SUB\%LINE 99 
99: WDIVD VI, VO, V2 

DBG> STEP © 

%SYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, 
mask=00000004, PC=000002E1, PSL=03C00010 
break on unhandled exception preceding .MAIN.\SUB\%LINE 100 
100: CLRL R0 

DBG> 

The comments that follow refer to the callouts in the previous example: 

© The command SET VECTOR_MODE SYNCHRONIZED causes the debugger 
to force automatic synchronization between the scalar and vector processors 
whenever a vector instruction is executed. 

© This STEP command suspends program execution on line 99, just before a 
WDIVD instruction is executed. Assume that, as in the previous example, 
the instruction will trigger a floating-point divide-by-zero exception. 
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® This STEP command executes the WDIVD instruction, which triggers the 
exception. Note that the vector exception is delivered immediately because 
the debugger is being operated in synchronized vector mode. 

Note that, in addition to SYNCHRONIZE VECTOR_MODE and SET VECTOR. 
MODE SYNCHRONIZED, a few other debugger commands can affect 
synchronization—for example, SET WATCH. 

11.9 Calling Routines That Might Affect the Program’s Vector State 

The CALL command’s /[NO]SAVE_VECTOR_STATE qualifiers enable you to 
control whether the current state of the vector processor is saved and then 
restored when a routine is called. 

The state of the VAX vector processor comprises the following: 

• The values of the vector registers and vector control registers 

• Any vector exception (an exception caused by the execution of a vector 
instruction) that might be pending delivery 

When you use the CALL command to execute a routine, execution of the routine 
might change the state of the vector processor as follows: 

• By chan g ing the values of vector registers or vector control registers 

• By causing a vector exception 

• By causing the delivery of a vector exception that was pending when the 
CALL command was issued 

The CALL/SAVE_VECTOR_STATE command specifies that the state of the vector 
processor that exists before the CALL command is issued is restored by the 
debugger after the called routine has completed execution. This ensures that, 
after the called routine has completed execution: 

• Any vector exception that was pending delivery before the CALL command 
was issued is still pending delivery 

• No vector exception that was triggered during the routine call is still pending 
delivery 

• The values of the vector registers are identical to their values before the 
CALL command was issued 

The CALL/NOSAVE_VECTOR_STATE command, which is the default, specifies 
that the state of the vector processor that exists before the CALL command is 
issued is not restored by the debugger after the called routine has completed 
execution. In this case, the state of the vector processor after the routine call 
depends on the effect (if any) of the called routine. 

The /[NO]SAVE_VECTOR_STATE qualifiers have no effect on the VAX general 
(scalar) registers. The values of these registers are always saved and restored 
when you execute a routine with the CALL command. 
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11.10 Displaying Vector Register Data in Screen Mode 

In screen mode, a register display shows the current values of the VAX general 
registers. (See Section 7.2.5.) 

To display data contained in vector registers or vector control registers in screen 
mode, use a DO display. (See Section 7.6.1.) 

For example, the following command creates a DO display named V2_DISP that 
shows the contents of elements 4 to 7 of register V2 (FORTRAN array syntax). 
The display is automatically updated whenever the debugger gains control from 
your program: 

DBG> DISPLAY V2_DISP AT RQ2 DO (EXAMINE %V2(4:7)) 
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Debugging Tasking Programs 


This chapter describes features of the debugger that are specific to taskin g 
programs (also called multithread programs). Tasking programs have multiple 
threads of execution within a VMS process and include the following: 

• Programs written in any language that use DECthreads or POSIX 1003.4a 
services. 

• Programs that use language-specific tasking services (services provided 
directly by the language). Currently, Ada is the only language with built-in 
tasking services that the debugger supports. 

Within the debugger, the term task denotes such a flow of control, regardless of 
the language or implementation. The debugger’s tasking support applies to all 
such programs. 

In this chapter, any DECthreads-specific or language-specific information is 
identified as such. Section 12.1 gives a cross reference between DECthreads 
terminology and Ada tasking terminology. 

The features in this chapter enable you to do functions such as the following: 

• Display task information. 

• Modify task characteristics to control task execution, priority, state 
transitions, and so on. 

• Monitor task-specific events and state transitions. 

When using these features, remember that the debugger might alter the 
behavior of a tasking program from run to run. For example, while you are 
suspending execution of the currently active task at a breakpoint, the delivery of 
an asynchronous system trap (AST) or a POSIX signal as some I/O is completed 
might make some other task eligible to run as soon as you allow execution to 
continue. 

For information about DECthreads or POSIX threads, see the corresponding 
documentation in the VMS documentation set. For information about Ada tasks, 
see the VAX Ada documentation. 

The debugging of multiprocess programs (programs that run in more than one 
process) is described in Chapter 10. 
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12.1 Comparison of DECthreads and Ada Terminology 

Table 12-1 compares DECthreads and Ada terminology and concepts. 

Table 12-1 Comparison of DECthreads and Ada Terminology 


DECthreads Terminology 

Ada Terminology 

Description 

Thread 

Task 

The flow of control within a 
process 

Thread object 

Task object 

The data item that represents 
the flow of control 

Object name or expression 

Task name or expression 

The data item that represents 
the flow of control 

Start routine 

Task body 

The code that is executed by the 
flow of control 

Not applicable 

Master task 

A parent flow of control 

Not applicable 

Dependent task 

A child flow of control that is 
controlled by some parent 

Synchronization object 

Rendezvous construct 

Method of synchronizing flows 

(mutex, conditionvariable) 

such as entry call or 
accept statement 

of control 

Scheduling policy and 
scheduling priority 

Task priority 

Method of scheduling execution 

Alert operation 

Abort statement 

Method of canceling a flow of 
control 

Thread state 

Task state 

Execution state (waiting, ready, 
running, terminated) 

Thread creation attribute 
(priority, scheduling policy, 
and so on) 

Pragma 

Attributes of the parallel entity 


12.2 Sample Tasking Programs 

The following sections present sample tasking programs with common errors that 
you might encounter when debugging tasking programs: 

• Section 12.2.1 describes a C program that uses DECthreads services 

• Section 12.2.2 describes an Ada program that uses the built-in Ada tasking 
services 

Some other examples in this chapter are derived from these programs. 

12.2.1 Sample C Multithread Program 

Example 12-1 is a multithread C program that shows incorrect use of condition 
variables, resulting in blocking. 

Explanatory notes are included after the example. Following these notes are 
instructions showing how to use the debugger to diagnose the blocking by 
controlling the relative execution of the threads. 

In the example, the initial thread creates two worker threads that do some 
computational work. Once the worker threads are created, a SHOW TASK/ALL 
command will show four tasks, each corresponding to a thread (Section 12.4 
explains use of the SHOW TASK command). 
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• %TASK 1 is the initial thread, which executes from main(). (Section 12.3.3 
defines task IDs, such as %TASK 1.) 

• %TASK 2 is the null thread, which does environment work in the background. 
%TASK 2 executes when no other threads are eligible to execute. 

• %TASK 3 and %TASK 4 are the worker threads. 

In the example, a synchronization point (a condition wait) has been placed in the 
workers’ path at line 3893. (The comment starting at line 3877 indicates that 
a straight call such as this one is incorrect programming and shows the correct 
code.) 

When the program executes, the worker threads are busy computing when the 
initial thread broadcasts on the condition variable. The first thread to wait on 
the condition variable detects the initial thread’s broadcast and clears it, leaving 
any remaining threads stranded. Execution is blocked and the program cannot 
terminate. 


Example 12-1 Sample C Multithread Program 


3777 

3778 

3779 

3780 

3781 

3782 

3783 

3784 

3785 

3786 

3787 

3788 
3799 

3790 

3791 

3792 

3793 

3794 

3795 

3796 
3787 

3798 

3799 

3800 

3801 

3802 

3803 

3804 

3805 

3806 

3807 

3808 

3809 

3810 

3811 

3812 

3813 

3814 

3815 

3816 


/* DEFINES */ 
#define NUM WORKERS 


/* Number of worker threads 


/* MACROS 

♦define check(status,string) \ 

if (status == -1) perror (string); 


/* GLOBALS 
int 

pthreadjnutexJ: 

pthread_cond_t 

pthreadjnutexJ: 


cv_predl; /* Condition Variable predicate 

cvjnutex; /* Condition Variable mutex 

cv; /* Condition Variable 

printjnutex; /* Print mutex 


*/ 

*/ 

*/ 

*/ 

*/ 


/* ROUTINES 

static pthread__startroutine_t 
workerjroutine (pthread_addr_t 


arg). 


main 

{ 


0 


pthread__t threads [NUM_WORKERS] ; 

/* Worker threads 

*/ 

int status; 

/* Return statuses 

*/ 

int exit; 

/* Join exit status 

*/ 

int result; 

/* Join result value 

*/ 

int i; 

/* Loop index 

n 

/* Initialize mutexes 


*/ 


£ -,-_-- * * - v- v ^uucaujiiutCAQU.l^uciaUXtj , 

check (status, "cvjnutex initilization bad status"); 

status = pthreadjnutex_init (Sprintjnutex, pthreadjnutexattrjiefault) ; 

check (status, "printjnutex intialization bad status"); 


/* Initialize condition variable 

status = pthread_cond_init (Scv, pthread__condattr__default) ; 
check (status, "cv condition init bad status"); 

/* Initialize condition variable predicate. 

cvjpredl =1; 0 

/* Create worker threads 

for (i = 0; i < NUM WORKERS; i++) { 0 


*/ 


(continued on next page) 
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Example 12-1 (Cont.) Sample C Multithread Program 


3817 

3818 

3819 

3820 

3821 

3822 

3823 

3824 

3825 

3826 

3827 

3828 

3829 

3830 

3831 

3832 

3833 

3834 

3835 

3836 

3837 

3838 

3839 

3840 

3841 

3842 

3843 

3844 

3845 

3846 

3847 

3848 

3849 

3850 

3851 

3852 

3853 

3854 

3855 

3856 

3857 

3858 

3859 

3860 

3861 

3862 

3863 

3864 

3865 

3866 

3867 

3868 

3869 

3870 

3871 

3872 

3873 

3874 

3875 

3876 

3877 


status = pthread_create ( 
&threads[i] 


check 

1 


(status, 


pthread_attr_default, 
worker jroutine, 

0 ); 

"threads create bad status"); 


h 


Set cv_predl to false; do this inside the lock to insure visibility. 


status = pthread_mutex_lock (&cv_mutex); 
check (status, "cvjnutex lock bad status"); 

cvjpredl = 0; 

status = pthreadjnutex_unlock (&cvjnutex); 
check (status, "cvjnutex unlock bad status"), 

/* Broadcast. */ 

status = pthread_cond_broadcast (&cv); 
check (status, "cv broadcast bad status"); 


0 


o 


0 


/* Attempt to join both of the worker threads. */ 
for (i = 0; i < NUM_WORKERS; i++) { 

exit = pthreadjjoin (threads[i], (pthread_addr_t*)&result); 
check (exit, "threads join bad status"); 

} 

) 


static pthread_startroutine_t 
worker jroutine(arg) 

pthread_addr_t arg; 

{ 

int sum; 
int iterations; 
int count; 
int status; 


0 


/* Do many calculations 
for (iterations = 1; iterations < 10001; 
sum = 1; 

for (count = 1; count < 10001; count++) 
sum = sum + count; 

} 


*/ 

iterations++) 


{ 


/* Printf may not be reentrant, so allow 1 thread at a time */ 

status = pthread_mutex_lock (&print_mutex); 
check (status, "print_mutex lock bad status"); 
printf (" The sum is %d \n", sum); 
status = pthread_mutex_unlock (&print_mutex); 
check (status, "printjnutex unlock bad status"); 

” /* Lock the mutex associated with this condition variable. pthread_cond_wait will */ 
/* unlock the mutex if the thread blocks on the condition variable. */ 

\ 

status = pthread_mutex_lock (&cv_mutex); 
check (status, "cv mutex lock bad status"); 


r 


In the next statement, the correct condition-wait syntax would be to loop 


*/ 


(continued on next page) 
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Example 

3878 

3879 

3880 

3881 

3882 

3883 

3884 

3885 

3886 

3887 

3888 
3888 

3890 

3891 

3892 

3893 

3894 

3895 

3896 

3897 

3898 

3899 

3900 

3901 

3902 

3903 


12-1 (Cont.) Sample C Multithread Program 

/* around the condition-wait call, checking the predicate associated with the */ 

/* condition variable. This would guard against condition waiting on a condition */ 
/ variable that may have already been broadcast upon, as well as spurious wake */ 
/* ups. Execution would resume when the thread is woken AND the predicate is 
/* false. The call would look like this: 


/* 

/* 

/* 

/* 

/* 

/* 

/* 

/* 

/* 


while (cv_predl) { 

status = pthread_cond_wait (Scv, &cv_mutex); 
check (status, "cv condition wait bad status"); 

A straight call, as used in the followingt code, might cause a thread to 
wake up when it should not (spurious) or become permanently blocked, as 
should one of the worker threads here. 


status = pthread_cond_wait (&cv, &cv_mutex); Q 

check (status, "cv condition wait bad status"); 

/* While blocking in the condition wait, the routine lets go of the mutex, but 
/* it retrieves it upon return. 

status = pthread_mutex_unlock (Scvjnutex); 
check (status, "cvjnutex unlock bad status"); 

return (int)arg; 

} 


*/ 

V 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


*/ 

*/ 


Key to Example 12-1: 

O The first few statements of main() initialize the synchronization objects 
used by the threads, as well as the predicate that is to be associated with 
the condition variable. The synchronization objects are initialized with the 
default attributes. The condition variable predicate is initialized such that a 
thread that is looping on it will continue to loop. At this point in the program, 
a SHOW TASK/ALL display lists %TASK 1 and %TASK 2. 

© The worker threads %TASK 3 and %TASK 4 are created. Here the created 
threads execute the same start routine (worker_routine) and hence can reuse 
the same call to pthreadjcreate with a slight change to store the different 
thread IDs. The threads are created using the default attributes and are 
passed an argument that is not used in this example. 

© The predicate associated with the condition variable is cleared in preparation 
to broadcast. This ensures that any thread awaking off the condition variable 
has received a valid wake-up and not a spurious one. Clearing the predicate 
also prevents any new arrivals from waiting on the condition variable because 
it has been broadcast or signaled upon. (The desired effect depends on correct 
coding being used for the condition wait call at line 3893, which is not the 
case in this example.) 

© The initial thread issues the broadcast call almost immediately, so that none 
of the worker threads should yet be at the condition wait. A broadcast should 
wake any threads currently waiting on the condition variable. 

As the programmer, you should ensure that a broadcast is seen, by either 
ensuring that all threads are waiting on the condition variable at the time 
of broadcast or ensuring that an associated predicate is used to flag that the 
broadcast has already happened. (Such measures have been left out of this 
example purposely.) 
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© The initial thread attempts to join with the worker threads to ensure that 
they exited properly. 

© When the worker threads execute worker_routine, they spend time doing 
many computations. This allows the initial thread to broadcast on the 
condition variable before either of the worker threads is waiting on it. 

© The worker threads then proceed to execute a pthread_cond_wa.it call, 
performing locks around the call as required. It is here that both worker 
threads will block, having missed the broadcast. A SHOW TASK/ALL 
command entered at this point would show both of the worker threads 
waiting on a condition variable. (Once the program is deadlocked in this way, 
you must press Ctrl/C to return control to the debugger.) 

The debugger enables you to control the relative execution of threads to diagnose 
problems of the kind shown in Example 12-1. In this case, you can suspend 
the execution of the initial thread and let the worker threads complete their 
computations so that they will be waiting on the condition variable at the time of 
broadcast. The following procedure explains how: 

1. At the start of the debugging session, set a breakpoint on line 3836 to suspend 
execution of the initial thread just prior to broadcast. 

2. Enter the GO command to execute the initial thread and create the worker 
threads. 

3. At this breakpoint, which causes the execution of all threads to be suspended, 
put the initial thread on hold with the SET TASK/HOLD %TASK 1 command. 

4. Enter the GO command to let the worker threads continue execution. The 
initial thread is on hold and cannot execute. 

5. When the worker threads block on the condition variable, press Ctrl/C to 
return control to the debugger at that point. A SHOW TASK/ALL command 
should indicate that both worker threads are suspended in a condition wait 
substate. (If not, enter GO to let the worker threads execute, then press Ctrl 
/C, and enter SHOW TASK/ALL, repeating the sequence until both worker 
threads are in a condition wait substate.) 

6. Enter the SET TASK/NOHOLD %TASK command 1 and then the GO 
command to allow the initial thread to resume execution and broadcast. 

This will enable the worker threads to join and terminate properly. 

12.2.2 Sample Ada Tasking Program 

Example 12-2 is an Ada tasking program. The labels («B1», and so on) in the 
example mark points of interest where breakpoints could be set and the state of 
each task observed. If you were to run the example under debugger control, you 
could enter the following command to set breakpoints at each label and display 
the current state of each task at the breakpoints (Section 12.4 explains how to 
use the SHOW TASK command): 

DBG> SET BREAK B1,B2,B3,B4,B5,B6,B7 DO (SHOW TASK/ALL) 

The program creates four tasks: 

• An environment task that runs the main program, TASK_EXAMPLE. This 
task is created before any library packages are elaborated (in this case, 
TEXT_IO). The environment task has the task ID %TASK 1 in the SHOW 
TASK displays (Section 12.3.3 defines task IDs). 


12-6 













Debugging Tasking Programs 
12.2 Sample Tasking Programs 


• A task object named FATHER. This task is declared by the main program and 
designated %TASK 2 in the SHOW TASK displays. 

• A single task named MOTHER. This task is declared by the main program 
and designated %TASK 3 in the SHOW TASK displays. 

• A single task named CHILD. This task is declared by task FATHER and 
designated %TASK 4 in the SHOW TASK displays. 


Example 12-2 Sample Ada Tasking Program 

1 Tasking program that demonstrates various tasking conditions. 

3 with TEXT_IO; use TEXT_IO; 

4 procedure TASK EXAMPLE is O 

5 

6 pragma TIME_SLICE(0.0); — Disable time slicing. © 

8 task type FATHER TYPE is 


9 

entry START; 


10 

entry RENDEZVOUS; 


11 

entry BOGUS; — Never accepted, caller deadlocks. 

12 

end FATHERJTYPE; 


13 



14 

FATHER : FATHER TYPE; © 


15 



16 

task body FATHERJTYPE is 


17 

SOME_ERROR : exception; 


18 



19 

task CHILD is © 


20 

entry E; 


21 

end CHILD; 


22 



23 

task body CHILD is 


24 

begin 


25 

FATHER TYPE.BOGUS; 


26 

end CHILD; 


27 



28 

CHILD deadlocks on call to its parent 


29 

(parent does not have an accept 


30 

31 

— statement for entry BOGUS). 


32 

33 

begin — (of FATHERJTYPE body) 


34 

accept START do 


35 

«B1» — Main program is waiting for this rendezvous to 

36 

— complete; CHILD is suspended when it 

calls the 

37 

— entry BOGUS. 


38 

null; 


39 

end START; 


40 



41 

PUT_LINE("FATHER is now active and"); © 


42 

PUT__LINE("is going to rendezvous with main 

program."] 

43 




(continued on next page) 
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Example 12-2 (Cont.) Sample Ada Tasking Program 


44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 
61 
62 
63 


for I in 1..2 loop 
select 

accept RENDEZVOUS do 

PUT LINE("FATHER now in rendezvous with main program"), 
end RENDEZVOUS; 
or 

terminate; 
end select; 

if I = 2 then 

raise SOME_ERROR; 
end if; 
end loop; 


exception 

when others => 

«B2» — CHILD is suspended on entry call to BOGUS. 

— Main program is going to delay while FATHER terminates. 
— MOTHER is ready to begin executing, 
abort CHILD; 

64 «B3» — CHILD is now abnormal due to the abort statement. 

65 

raise; — SOME_ERROR exception terminates FATHER, 
end FATHER TYPE; 


66 

67 

68 

69 

70 

71 

72 

73 

74 

75 

76 

77 

78 

79 

80 
81 
82 

83 begin 
«B5» 


task MOTHER is © 
entry START; 
pragma PRIORITY (6); 
end MOTHER; 

task body MOTHER is 
begin 

accept START; 

«B4» — At this point, the main program is waiting for its 

— dependents (FATHER and MOTHER) to terminate. FATHER 

— is terminated, 
null; 

end MOTHER; 


84 

85 

86 

87 

88 

89 

90 

91 

92 

93 

94 

95 

96 

97 

98 

99 
100 
101 
102 


- (of TASK_EXAMPLE) © 

- FATHER is suspended at accept start. 

— CHILD is suspended in its deadlock. 

— MOTHER has activated and is ready to begin executing. 
FATHER.START; © 

«B6» — FATHER is suspended at its 'select or terminate' 

— statement. 


FATHER.RENDEZVOUS; © 

FATHER.RENDEZVOUS; © 
loop ® 

— This loop causes the main program to busy wait 

— for the termination of FATHER, so that FATHER 

— can be observed in its terminated state, 
if FATHER'TERMINATED then 

exit; 
end if; 
delay 1.0; 
end loop; 


(continued on next page) 
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Example 12-2 (Cont.) Sample Ada Tasking Program 

103 «B7» — FATHER has terminated by now with the unhandled 

104 " exception SOME_ERROR. CHILD no longer exists 

because its master (FATHER) has terminated. Task 

106 — MOTHER is ready. 

107 MOTHER.START; © 

108 — The main program enters a wait-for-dependents state, 

109 so that MOTHER can finish executing. 

110 end TASK_EXAMPLE; © 

Key to Example 12-2: 

O After all Ada library packages are elaborated (in this case, TEXT_IO), the 
main program is automatically called and begins to elaborate its declarative 
part (lines 5 to 82). 

© To ensure repeatability from run to run, the example uses no time slicing (see 
Section 12.5.2). The 0.0 value for the pragma TIMEJSLICE documents that 
the procedure TASK.EXAMPLE needs to have time slicing disabled (time 
slicing is disabled if the pragma TIME.SLICE is omitted or is specified with 
a value of 0.0). 

© Task object FATHER is elaborated, and a task designated %TASK 2 is 

created. FATHER (%TASK 2) is created in a suspended state (see Table 12-3). 
and is not activated until the beginning of the statement part of the main 
program (line 83), in accordance with Ada rules. The elaboration of the task 
body on lines 16 to 67 defines the statements that tasks of type FATHER. 
TYPE will execute. 

© Task FATHER declares a single task named CHILD (line 19). A single task 
represents both a task object and an anonymous task type. Task CHILD is 
not created or activated until FATHER is activated. 

© The only source of ASTs is this series of TEXT_IO.PUT_LINE statements 
(input-output completion delivers ASTs). 

© A single task, MOTHER, is defined, and a task designated %TASK 3 is 
created. The pragma PRIORITY gives MOTHER a priority of 6. 

© The tasks FATHER and MOTHER are activated in parallel while the main 
program waits. FATHER has no pragma PRIORITY and thus assumes a 
default priority of 7. Because this is higher than the priority of MOTHER, 
FATHER executes its activation first. Its activation consists of the elaboration 
of lines 16 to 31. 

When task FATHER is activated, it waits while its task CHILD is activated 
and a task designated %TASK 4 is created. CHILD executes one entry call 
on line 25, and then deadlocks because the entry is never accepted (see 
Section 12.7.1). 

© This is the first rendezvous that the main program makes with task FATHER. 
This rendezvous causes FATHER to be suspended at its first accept statement 
(line 34). Note that FATHER continues to execute past the end of its 
activation, even though MOTHER has not been activated. This is because 
VAX Ada attempts to continue tasks as far as they will go to minimize task 
switch overhead. When FATHER becomes suspended, MOTHER begins its 
activation, and executes lines 74 and 75. 
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O After tasks FATHER and MOTHER are activated, the main program 

(%TASK 1) is eligible to resume execution. Because %TASK 1 has the default 
priority of 7, which is higher than MOTHER’S priority, the main program 
resumes execution. 

® At the third rendezvous with FATHER, FATHER raises the exception SOME_ 
ERROR on line 54. The handler on line 59 catches the exception, aborts 
the suspended CHILD task, and then reraises the exception. FATHER then 
terminates. 

<D A loop with a delay statement ensures that when control reaches line 103, 
FATHER has executed far enough to be terminated. 

<£ This entry call ensures that MOTHER does not wait forever for its rendezvous 
on line 76. MOTHER executes the accept statement (which involves no other 
statements), the rendezvous is completed, and MOTHER is immediately 
switched off the processor at line 77 because its priority is only 6. 

0 After its rendezvous with MOTHER, the main program (%TASK 1) executes 
lines 108 to 110. At line 110, the main program must wait for all its 
dependent tasks to terminate (see Section 12.6.4). When the main program 
reaches line 110, the only nonterminated task is MOTHER (which cannot 
terminate until the null statement at line 80 has executed). MOTHER finally 
executes to completion at line 81. Now that all tasks are terminated, the 
main program completes execution. The main program then returns and 
execution resumes with the VMS command-line interpreter. 

12.3 Specifying Tasks in Debugger Commands 

A task is an entity that executes in parallel with other tasks. A task is 
characterized by a unique task ID (defined in Section 12.3.3), a separate stack, 
and a separate register set. 

The current definition of the active task and of the visible task determine the 
context for manipulating tasks. See Section 12.3.1. 

When specifying tasks in debugger commands, you can use any of the following 
forms: 

• A task (thread) name as declared in the program (for example FATHER 
in Section 12.2.2) or a language expression that yields a task value. 

Section 12.3.2 describes Ada language expressions for tasks. 

• A task ID (for example, %TASK 2). See Section 12.3.3. 

• A task built-in symbol (for example, %ACTIVE_TASK). See Section 12.3.4. 

12.3.1 Definition of Active Task and Visible Task 

The active task is the task that runs when a STEP, GO, CALL, or EXIT 
command executes. Initially, it is the task in which execution is suspended when 
the debugger is invoked. To change the active task during a debugging session, 
use the SET TASK/ACTIVE command. For example, the following command 
makes the task named CHILD the active task: 

DBG> SET TASK/ACTIVE CHILD 
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The visible task is the task whose stack and register set are the current context 
that the debugger uses when looking up symbols, register values, routine calls, 
breakpoints, and so on. For example, the following command displays the value 
of the variable KEEP.COUNT in the context of the visible task: 

DBG> EXAMINE KEEP_COUNT 

Initially, the visible task is the active task. To change the visible task, use the 
SET TASK/VISIBLE command. This enables you to look at the state of other 
tasks without affecting the active task. 

You can specify the active and visible tasks in debugger commands by using 
the built-in symbols %ACTIVE_TASK and %VISIBLE_TASK, respectively (see 
Section 12.3.4). 

See Section 12.5 for more information about using the SET TASK command to 
modify task characteristics. 

12.3.2 Ada Tasking Syntax 

You declare a task either by declaring a single task or by declaring an object of a 
task type. For example: 

— TASK TYPE declaration, 
task type FATHER_TYPE is 

end FATHER_TYPE; 

task body FATHER_TYPE is 

end FATHER_TYPE; 

— A single task. 

task MOTHER is 

end MOTHER; 

task body MOTHER is 

end MOTHER; 

A task object is a data item that contains a 32-bit task value. A task object 
is created when the program elaborates a single task or task object, when you 
declare a record or array containing a task component, or when a task allocator is 
evaluated. For example: 

-- Task object declaration. 

FATHER : FATHER_TYPE; 

Task object (T) as a component of a record. 

type SOME_RECORD_TYPE is 

record 

A, B: INTEGER; 

T : FATHER_TYPE; 

end record; 

HAS_TASK : SOME_RECORD_TYPE; 

— Task object (P0INTER1) via allocator. 

type A is access FATHER_TYPE; 

POINTERl : A := new FATHER TYPE; 
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A task object is comparable to any other object. You refer to a task object in 
debugger commands either by name or by path name. For example: 

dbg> examine father 

dbg> examine father_type$task_body.child 

When a task object is elaborated, a task is created by the VAX Ada run-time 
library, and the task object is assigned its 32-bit task value. As with other Ada 
objects, the value of a task object is undefined before the object is initialized, and 
the results of using an uninitialized value are unpredictable. 

The task body of a task type or single task is implemented in VAX Ada as a 
procedure. This procedure is called by the VAX Ada run-time library when a task 
of that type is activated. A task body is treated by the debugger as a normal Ada 
procedure, except that it has a specially constructed name. 

lb specify the task body in a debugger command, use the following syntax to refer 
to tasks declared as task types: 

task-type-identifier$TASK_BODY 

Use the following syntax to refer to single tasks: 

task-identifiei$TASK_BODY 

For example: 

DBG> SET BREAK FATHER_TYPE$TASK_BODY 

The debugger does not support the task-specific Ada attributes T' CALLABLE, 

E' COUNT, T' STORAGE_SIZE, and T'TERMINATED, where T is a task type 
and E is a task entry (see the VAX Ada documentation for more information 
on these attributes). So you cannot enter commands such as EVALUATE 
CHILD'CALLABLE. However, you can get the information provided by each 
of these attributes with the debugger SHOW TASK command. For more 
information, see Section 12.4. 

12.3.3 Task ID 

A task ID is the number assigned to a task when it is created by the tasking 
system. The task ID uniquely identifies a task during the entire execution of a 
program. 

A task ID has the following syntax, where n is a positive decimal integer: 

%TASK n 

You can determine the task ID of a task object by evaluating or examining the 
task object. For example (Ada path-name syntax): 

DBG> EVALUATE FATHER 
ITASK 2 

DBG> EXAMINE FATHER 
TASK_EXAMPLE.FATHER: ITASK 2 

If the programming language does not have built-in tasking services, you must 
use the EXAMINE/TASK command to obtain the task ID of a task. 

Note that the EXAMINE/TASK/HEXADECIMAL command, when applied to a 
task object, yields the hexadecimal task value. The task value is the address of 
the task (or thread) control block of that task. For example (Ada example): 

DBG> EXAMINE/HEXADECIMAL FATHER 
TASK_EXAMPLE.FATHER: 0015AD00 
DBG> 
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The SHOW TASK/ALL command enables you to identify the task IDs that have 
been assigned to all currently existing tasks. The following examples are derived 
from Example 12—1 and Example 12—2, respectively: 


DBG> SHOW TASK/ALL 
task id state hold pri substate 
ITASK 1 READY HOLD 12 

* ITASK 2 RUN 

%TASK 3 SUSP 

ITASK 4 SUSP 

DBG> 

DBG> SHOW TASK/ALL 
task id pri hold state 

* ITASK 1 7 run 

ITASK 2 
ITASK 4 
ITASK 3 

DBG> 


thread_object 
Initial thread 
Null thread 

THREAD_EXl\main\threads[0].fieldl 
THREAD_EXl\main\threads[1].fieldl 


task object 
SHARE $ADARTL+13 0428 
TASK_EXAMPLE.MOTHER+4 

TASK_EXAMPLE.FATHER_TYPE$TASK BODY.CHILD+4 
TASK EXAMPLE.MOTHER+4 


12 Condition Wait 
12 Condition Wait 


substate 
SUSP Accept 

7 SUSP Entry call 

6 READY 


You can use task IDs to refer to nonexistent tasks in debugger conditional 
statements. For example, if you had already run your program once, and you 
discovered that %TASK 2 and 3 were of interest, you could enter the following 
commands at the beginning of your next debugging session before %TASK 2 or 3 
was created: 


DBG> SET BREAK ILINE 44 WHEN (IACTIVE TASK=ITASK 3) 

DBG> IF (ICALLER=ITASK 3) THEN (SHOW TASK/FULL) 

In other words, you can use a task ID in certain debugger commands before the 
task has been created without the debugger reporting an error (as it would if you 
used a task object name before the task object came into existence). A task does 
not exist until the task is created. Later the task becomes nonexistent sometime 
after it terminates. A nonexistent task never appears in a debugger SHOW TASK 
display. 

Each time a program runs, the same task IDs are assigned to the same tasks 
so long as the program statements are executed in the same order. Different 
execution orders can result from ASTs (caused by delay statement expiration or 
input-output completion) being delivered in a different order. Different execution 
orders can also result from time slicing being enabled. A given task ID is never 
reassigned during the execution of the progr am 

For all types of tasks, the run-time library always assigns %TASK 1 to the task 
that executes the main program. For DECthreads tasks, the run-time library 
always assigns %TASK 2 to the null task that executes when there are no other 
tasks—including the main propam—eligible to execute. The null task is a special 
task created by the run-time library; you cannot apply most debugger commands 
to the null task. %TASK 0 refers to a nonexistent task (not the null task). 

12.3.4 Task Built-In Symbols 

The debugger built-in symbols defined in Table 12—2 enable you to specify tasks 
in command procedures and command constructs. 
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Table 12-2 Task Bui lt-In Symbols _ _ 

Built-in Symbol_ Description ___ 

%ACTIVE_TASK The task that runs when a GO, STEP, CALL, or EXIT 

command executes. 


%CALLER_TASK 

%NEXT_TASK 

%PRE VIOU S_TASK 
%VISIBLE_TASK 


(Applies only to Ada programs.) When an accept statement 
executes, the task that called the entry associated with the 
accept statement. 

The task after the visible task in the debugger’s task list. The 
ordering of tasks is arbitrary but consistent within a single run 
of a program. 

The task previous to the visible task in the debugger’s task 
list. 

The task whose call stack and register set are the current 
context for looking up symbols, register values, routine calls, 
breakpoints, and so on. 


Examples using these task built-in symbols follow. 

The following command obtains the task ID of the visible task: 

DBG> EVALUATE %VISIBLE_TASK 

The following command places the active task on hold: 

DBG> SET TASK/HOLD %ACTIVE_TASK 

The following command sets a breakpoint on line 25 that triggers only when task 
CHILD executes that line: 

DBG> SET BREAK %LINE 25 WHEN (%ACTIVE_TASK=CHILD) 

The symbols %NEXT_TASK and %PREVIOUS_TASK enable you to cycle through 
the total set of tasks that currently exist. For example: 

DBG> SHOW TASK %VISIBLE_TASK; SET TASK/VISIBLE %NEXT_TASK 
DBG> SHOW TASK %VISIBLE TASK; SET TASK/VISIBLE %NEXT_TASK 


DBG> EXAMINE MONITOR_TASK 
M0D\M0NIT0R TASK: %TASK 2 

DBG> WHILE %NEXT_TASK NEQ IACTIVE DO (SET TASK %NEXT_TASK; SHOW CALLS) 

12.3.4.1 Caller Task Symbol (Ada) 

The symbol %CALLER_TASK is specific to Ada tasks. It evaluates to the task ID 
of the task that called the entry associated with the accept statement. Otherwise, 
it evaluates to %TASK 0. For example, %CALLER_TASK evaluates to %TASK 0 
if the active task is not currently executing the sequence of statements associated 
with the accept statement. 

For example, suppose a breakpoint has been set on line 48 of Example 12-2 
(within an accept statement). The accept statement in this case is executed 
by task FATHER (%TASK 2) in response to a call of entry RENDEZVOUS by 
the main program (%TASK 1). Thus, when an EVALUATE %CALLER_TASK 
command is entered at this point, the result is the task ID of the calling task, the 
main program: 

DBG> EVALUATE %CALLER_TASK 

%TASK 1 

DBG> 
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When the rendezvous is the result of an AST entry call, %CALLER_TASK 
evaluates to %TASK 0 because the caller is not a task. 

12.4 Obtaining Information About Tasks 

To obtain information about one or more tasks of your progr am use the SHOW 
TASK command. 

The SHOW TASK command displays information about existing (nonterminated) 

tasks. By default, the command displays one line of information about the visible 
task. 

Section 12.4.1 and Section 12.4.2 describe the information displayed by a SHOW 
TASK command for DECthreads and Ada tasks, respectively. 

12.4.1 Obtaining Information about DECthreads Tasks 

The command SHOW TASK/ALL displays information about all of the tasks of 
the program that currently exist (see Example 12-3). 


Example 12-3 Sample SHOW TASK/ALL Display for DECthreads Tasks 


o 


© 

task id 

state : 

%TASK 

1 

SUSP 

%TASK 

2 

READY 

%TASK 

3 

SUSP 

ITASK 

4 

SUSP 

%TASK 

5 

SUSP 

* %TASK 

6 

RUN 

%TASK 

7 

READY 

%TASK 

8 

SUSP 

%TASK 

9 

READY 

ITASK 

10 

TERM 


DBG> 


o © 

pri substate 

12 Condition Wait 
0 

12 Mutex Wait 
12 Delay 
12 Mutex Wait 
12 
12 

12 Mutex Wait 
12 

12 Term, by alert 


© 

thread_object 
Initial thread 
Null thread 

T_EXAMP\main\threads[0].fieldl 
T_EXAMP\main\threads[l].fieldl 
T_EXAMP\main\threads[2].fieldl 
T_EXAMP\main\threads[3].fieldl 
T_EXAMP\main\threads[4].fieldl 
T_EXAMP\main\threads[5].fieldl 
T_EXAMP\main\threads[6].fieldl 
T_EXAMP\main\threads[7].fieldl 


Key to Example 12-3: 

O The task ID (see Section 12.3.3). The active task is marked with an asterisk 
(*) in the leftmost column. 


© The current state of the task (see Table 12-3). The task in the RUN 
(RUNNING) state is the active task. Table 12—3 lists the state transitions 
possible during program execution. 

© Whether the task has been put on hold with a SET TASK/HOLD command, 
as explained in Section 12.5.1. 

© The task priority. 

© The current substate of the task. The substate helps indicate the possible 
cause of a task’s state. See Table 12-4. 

© A debugger path name for the task (thread) object or the address of the task 
object if the debugger cannot symbolize the task object. 
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Table 12-3 Generic Task States 


Task State 

Description 

RUNNING 

Task is currently running on the processor. This is the active task. A 
task in this state can make a transition to the READY, SUSPENDED, 
or TERMINATED state. 

READY 

Task is eligible to execute and waiting for the processor to be made 
available. A task in this state can make a transition only to the 
RUNNING state. 

SUSPENDED 

Task is suspended—that is, waiting for an event rather than for the 
availability of the processor. For example, when a task is created, it 
remains in the suspended state until it is activated. A task in this 
state can make a transition only to the READY or TERMINATED 
state. 

TERMINATED 

Task is terminated. A task in this state cannot make a transition to 
another state. 


Table 12-4 DECthreads Task Substates 


Task Substate 

Description 

Condition Wait 

Delay 

Mutex Wait 

Not yet started 
Term, by alert 
Term, by exc 

Task is waiting on a DECthreads condition variable. 

Task is waiting at a call to a DECthreads delay. 

Task is waiting on a DECthreads mutex. 

Task has not yet executed its start routine. 

Task has been terminated by an alert operation. 

Task has been terminated by an exception. 


Timed Cond Wait Task is waiting on a timed DECthreads condition variable. 


The SHOW TASK/FULL command provides detailed information about each 
task selected for display. Example 12-4 shows the output of this command for a 
sample DECthreads task. 
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Example 12-4 Sample SHOW TASK/FULL Display for a DECthreads Task 


O task id state hold pri substate 
ITASK 4 SUSP 12 Delay 

© Alert is pending 

Alerts are deferred 


thread_object 

T__EXAMP\main\threads [1] .fieldl 


© 

© 

© 

© 

© 

DBG> 


Next pc: 

SHARE$CMA$RTL+46136 

Start routine: 

T EXAMP\thread action 

Scheduling policy: 

throughput 


Stack storage: 
Bytes in use: 

1288 

© Base: 00334C00 

Bytes available: 

40185 

SP: 003346F8 

Reserved Bytes: 

10752 

Top: 00329A00 

Guard Bytes: 

4095 

Thread control block: 


Size: 

293 

Address: 00311B78 

Total storage: 

56613 



Key to Example 12-4: 

© Identifying information about the task. 

© Bulletin-type information about something unusual. 

© Next execution PC value and start routine. 

© Task scheduling policy. 

© Stack storage information: 

• "Bytes in use:" the number of bytes of stack currently allocated. 

• "Bytes available:" the unused space in bytes. 

• "Reserved bytes:" the storage allocated for handling stack overflow. 

• "Guard bytes:" the size of the "guard area" or unwritable part of the 
stack. 

© Minimum and maximum addresses of the task stack. 

© Task (thread) control block information. The task value is the address, in 
hexadecimal notation, of the task control block. 

© The total storage used by the task. Adds together the task control block size, 
the number of reserved bytes, the top guard size, and the storage size. 

Figure 12-1 shows a task stack. 
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Figure 12-1 Diagram of a Task Stack 


low address 


001EB600: 


001F2C38: 

001FD2FC: 


00077D40: 

(490816) 

high address 


> 

1 


top guard (8 pages) 


reserved bytes (~21 pages) 


:top 

address 




:sp 

:base 

address 


bytes 
in use 


storage 

size 


^-task control block 


ZK-3333A-GE 


The SHOW TASK/STATISTICS command reports some statistics about all 
tasks in your program. Example 12—5 shows the output of the SHOW TASK 
/STATISTICS/FULL command for a sample program with DECthreads tasks. 
This information enables you to measure the performance of your program. The 
larger the number of total schedulings (also known as context switches), the more 
tasking overhead there is. 

Example 12-5 Sample SHOW TASK/STAT/FULL Display for DECthreads Tasks 

task statistics 

Total context switches: 0 

Number of existing threads: 0 

Total threads created: 0 

DBG> 
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12.4.2 Obtaining Task Information About Ada Tasks 

The SHOW TASK/ALL command displays information about all of the tasks 
of the program that currently exist—namely, tasks that have been created and 
whose master has not yet terminated (see Example 12-6). 


Example 12-6 Sample SHOW TASK/ALL Display for Ada Tasks 

0 0 0 © 0 0 

task id pri hold state substate task object 

* %TASK 1 7 RUN SHARE$ADARTL+130428 

%TASK 2 7 HOLD SUSP Accept TASK_EXAMPLE.MOTHER+4 

%TASK 4 7 SUSP Entry call TASK_EXAMPLE.FATHER TYPE$TASK BODY.CHILD+4 

■sTASK 3 6 READY TASK EXAMPLE.MOTHER) 

DBG> 

Key to Example 12-6: 

O The task ID (see Section 12.3.3). The active task is marked with an asterisk 
(*) in the leftmost column. 

© The task priority. Ada priorities range from 0 to 15. 

0 Whether the task has been put on hold with a SET TASK/HOLD command, 
as explained in Section 12.5.1. 

© The current state of the task (see Table 12-3). The task that is in the RUN 
(RUNNING) state is the active task. Table 12-3 lists the state transitions 
possible during program execution. 

© The current substate of the task. The substate helps indicate the possible 
cause of a task’s state. See Table 12-5. 

© A debugger path name for the task object or the address of the task object if 
the debugger cannot symbolize the task object. 


Table 12-5 Ada Task Substates 


Task Substate 

Description 

Abnormal 

Task has been aborted. 

Accept 

Task is waiting at an accept statement that is not inside a select 
statement. 

Activating 

Task is elaborating its declarative part. 

Activating tasks 

Task is waiting for tasks it has created to finish activating. 

Completed [abn] 

Task is completed due to an abort statement but is not yet 
terminated. In Ada, a completed task is one that is waiting 
for dependent tasks at its end statement. After the dependent 
tasks are terminated, the state changes to terminated. 

Completed [exc] 

1 A , „ , 

Task is completed due to an unhandled exception 1 is not yet 
terminated. In Ada, a completed task is one that is waiting for 
dependent tasks at its end statement. After the dependent tasks 
are terminated, the state changes to terminated. 


» U U . U .< U 1 U 1 CU exception is one ior wmcn tnere is no handler in the current frame or for wh 
is a handler that executes a raise statement and propagates the exception to an outer scope. 


(continued on next page) 
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Table 12-5 (Cont.) 

Ada Task Substates 

Task Substate 

Description 

Completed 

Task is completed. No abort statement was issued and no 

unhandled exception 1 occurred. 

Delay 

Task is waiting at a delay statement. 

Dependents 

Task is waiting for dependent tasks to terminate. 

Dependents [exc] 

Task is waiting for dependent tasks to allow an unhandled 
exception 1 to propagate. 

Entry call 

Task is waiting for its entry call to be accepted. 

Invalid state 

There is an error in the VAX Ada run-time library. 

I/O or AST 

Task is waiting for input-output completion or some AST. 

Not yet activated 

Task is waiting to be activated by the task that created it. 

Select or delay 

Task is waiting at a select statement with a delay 
alternative. 

Select or terminate 

Task is waiting at a select statement with a terminate alternative. 

Select 

Task is waiting at a select statement with no else, delay, or 
terminate alternative. 

Shared resource 

Task is waiting for an internal shared resource. 

Terminated [abn] 

Task was terminated by an abort statement. 

Terminated [exc] 

Task was terminated because of an unhandled exception . 1 

Terminated 

Task terminated normally. 

Timed entry call 

Task is waiting in a timed entry call. 

1 An unhandled exception is one for which there is no handler in the current frame or for which there 

is a handler that executes a raise statement and propagates the exception to an outer scope. 


Figure 12-1 shows a task stack. For Ada tasks, the top guard is 10 pages, rather 
than 8. 

The SHOW TASK/FULL command provides detailed information about each 
task selected for display. Example 12-7 shows the output of this command for a 
sample Ada task. 


Example 12-7 Sample SHOW TASK/FULL Display for an ADA Task 


O task id 
* %TASK 2 


pri hold state substate 
7 RUN 


task object 
TASK EXAMPLE.M0THER+4 


0 Waiting entry callers: 

Waiters for entry BOGUS: 
%TASK 4, type: CHILD 


(continued on next page) 
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Example 12-7 (Cont.) Sample SHOW TASK/FULL Display for an ADA Task 


O 


0 


DBG> 


FATHER_TYPE 

TASK_EXAMPLE.ILINE 14+22 
ITASK 1 

TASK EXAMPLE.FATHER TYPE$TASK BODY 


Task type: 

Created at PC: 

Parent task: 

Start PC: 

Task control block: 

Task value: 490816 
Entries: 3 

Size: 1488 

Stack addresses: 

Top address: 001EB600 
Base address: 001F2DFC 


0 Stack storage (bytes): 
RESERVED_BYTES: 
TOP_GUARD_SIZE: 
STORAGE_SIZE: 

Bytes in use: 

0 Total storage: 


10640 

5120 

30720 

456 

47968 


Key to Example 12-7: 

O Identifying information about the task. 

© Rendezvous information. If the task is a caller task, lists the entries for which 
it is queued. If the task is to be called, gives information about the kind of 
rendezvous that will take place and lists the callers that are currently queued 
for any of the task’s entries. 

0 Task context information. 

© Task control block information. The task value is the address, in decimal 
notation, of the task control block. 

© Stack storage information: 

• RESERVED.BYTES gives the storage allocated by the Ada run-time 
library for handling stack overflow. 

• TOP_GUARD_SIZE gives the storage allocated for guard pages, which 
provide protection against storage overflow during task execution. You 
can specify the number of bytes to be allocated as guard pages with the 
VAX Ada pragmas TASK_STORAGE and MAIN_STORAGE; the number 
shown by the debugger is the number of bytes allocated (the pragma value 
is rounded up to an integral number of pages, as necessary). For more 
information about these pragmas and the top guard storage area, see the 
VAX Ada documentation. 

• STORAGE_SIZE gives the storage allocated for the task activation. You 
can specify the number of bytes to be allocated with the T' STORAGE. 
SIZE representation clause or in the VAX Ada pragma MAIN.STORAGE; 
the number shown by the debugger is the number of bytes allocated 
(the value specified is rounded up to an integral number of pages, as 
necessary). For more information about this representation clause and 
pragma and about the task activation (working) storage area, see the 
VAX Ada documentation. 

• "Bytes in use:" gives the number of bytes of stack currently allocated. 

0 Stack addresses of the task stack. 

© The total storage used by the task. Adds together the task control block size, 
the number of reserved bytes, the top guard size, and the storage size. 
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The SHOW TASK/STATISTICS command reports some statistics about all 
tasks in your program. Example 12—8 shows the output of the SHOW TASK 
/STATISTICS/FULL command for a sample Ada tasking program. This 
information enables you to measure the performance of your program. The 
larger the number of total schedulings (also known as context switches), the more 
tasking overhead there is. 


Example 12-8 Sample SHOW TASK/STATISTICS/FULL Display for Ada Tasks 


task statistics 

Entry calls = 4 

Tasks activated = 3 

ASTs delivered = 4 

Total schedulings = 15 


Accepts = 1 Selects = 2 
Tasks terminated = 0 
Hibernations = 0 


a higher priority task 
vations 

Due to suspended entry calls 
:cepts 
ilects 
a DELAY 

Due to scope exit awaiting dependents 

Due to exception awaiting dependents 

Due to waiting for I/O to complete 

Due to delivery of an AST 

Due to task terminations 

Due to shared resource lock contention 


Due 

to 

Due 

to 

Due 

to 

Due 

to 

Due 

to 

Due 

to 

Due 

to 

Due 

to 

Due 

to 

Due 

to 

Due 

to 

Due 

to 


1 

3 

4 
1 
2 
0 

■ 0 
■ 0 
0 
4 

- 0 
« 0 


DBG> 


12.5 Changing Task Characteristics 

To modify a task’s characteristics or the tasking environment while debugging, 
use the SET TASK command as shown in the following table. 


Command Description 


SET TASK/ACTIVE 
SET TASK/VISIBLE 
SET TASK/ABORT 


SET TASK/PRIORITY 
SET TASK/RESTORE 
SET TASK/[NO]HOLD 
SET TASK/TIME_SLICE 


Makes a specified task the active task (see Section 12.3.1). 
Makes a specified task the visible task (see Section 12.3.1). 

Requests that a task be terminated at the next allowed 
opportunity. The exact effect depends on the current 
event facility (language dependent). For Ada tasks, this 
is equivalent to executing an abort statement. 

Sets a task’s priority. The exact effect depends on the current 
event facility (language dependent). 

Restores a task’s priority The exact effect depends on the 
current event facility (language dependent). 

Controls task switching (task state transitions, see 
Section 12.5.1). 

Controls the time slice value or disable time slicing (see 
Section 12.5.2). 


For more information about the SET TASK command and its qualifiers, see the 
command dictionary. 
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12.5.1 Putting Tasks on Hold to Control Task Switching 

Task switching might be confusing when you are debugging a program. Placing a 
task on hold with the SET TASK/HOLD command restricts the state transitions 
the task can make once the program is subsequently allowed to execute. 

A task placed on hold can enter any state except the RUNNING state. However, 
if necessary, you can force it into the RUNNING state by u sing the SET TASK ' 
/ACTIVE command. 

The SET TASK/HOLD/ALL command freezes the state of all tasks except the 
active task. You can use this command in combination with the SET TASK 
/ACTIVE command to observe the behavior of one or more specified tasks in 
isolation, by executing the active task with the STEP or GO command, and then 
switching execution to another task with the SET TASK/ACTIVE command. For 
example: 

DBG> SET TASK/HOLD/ALL 
DBG> SET TASK/ACTIVE ITASK 1 
DBG> GO 


DBG> SET TASK/ACTIVE ITASK 3 
DBG> STEP 


When you no longer wish to have a task held, use the SET TASK/NOHOLD 
command. 

12.5.2 Debugging Programs That Use Time Slicing 

Tasking programs that use time slicing are difficult to debug because time slicing 
makes the relative behavior of tasks asynchronous. Without time slicing, task 
execution is determined solely by task priority; task switches are predictable 
and the behavior of the program is repeatable from one run to the next. With 
time slicing, task priorities still govern task switches, but tasks of the same 
priority also take turns executing for a specified period of time. Thus, time slicing 
causes tasks to execute more independently from each other, and the behavior 
of a program that uses time slicing might not be repeatable from one run of the 
program to the next. 

The SET TASK/TIME_SLICE=£ command enables you to specify a new time slice 
or disable time slicing (with SET TASK/TIME_SLICE=0.0). Thus, you can tune 
the execution of your tasking programs or diagnose problems that depend on the 
order in which tasks execute. 

Note that there is an interaction between time slicing and the debugger 
watchpoint implementation. When you set watchpoints, the debugger might 
automatically increase the value of the time-slice interval to 10.0 seconds. 
Slowing the time-slice rate prevents some problems. 
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12.6 Controlling and Monitoring Execution 

The following sections explain how to do the following functions: 

• Set task-specific and task-independent eventpoints (breakpoints, tracepoints, 
and so on) 

• Set breakpoints and tracepoints on DECthreads-specific task locations. 

• Set breakpoints and tracepoints on Ada-specific task locations. 

• Monitor task events with the SET BREAK/EVENT or SET TRACE/EVENT 
commands 

12.6.1 Setting Task-Specific and Task-Independent Debugger Eventpoints 

An eventpoint is an event that you can use to return control to the debugger. 
Breakpoints, tracepoints, watchpoints, and the completion of STEP commands 
are eventpoints. 

A task-independent eventpoint can be triggered by the execution of any task 
in a program, regardless of which task is active when the eventpoint is set. Task- 
independent eventpoints are generally specified by an address expression such as 
a line number or a name. All watchpoints are task-independent eventpoints. The 
following are examples of setting task-independent eventpoints: 

DBG> SET BREAK COUNTER 

DBG> SET BREAK/NOSOURCE %LINE 42, CHILD$TASK_BODY 
DBG> SET WATCH/AFTER=3 KEEP_COUNT 

A task-specific eventpoint can be set only for the task that is active when 
the command is entered. A task-specific eventpoint is triggered only when that 
same task is active. For example, the STEP/LINE command is a task-specific 
eventpoint: other tasks might execute the same source line and not trigger the 
event. 

If you use the SET BREAK, SET TRACE, or STEP commands with the following 
qualifiers, the resulting eventpoints are task specific: 

/BRANCH 

/CALL 

/INSTRUCTION 

/LINE 

/RETURN 

/VECTORJNSTRUCTION 

Any other eventpoints that you set with those commands and any eventpoints 
that you set with the SET WATCH command are task independent. 

The following are examples of setting task-specific eventpoints: 

DBG> SET BREAK/INSTRUCTION 

DBG> SET TRACE/INSTRUCTION/SILENT DO (EXAMINE KEEP_COUNT) 

DBG> STEP/CALL/NOSOURCE 

You can conditionalize eventpoints that are normally task-independent to make 
them task specific. For example: 

DBG> SET BREAK %LINE 10 WHEN (%ACTIVE_TASK=FATHER) 
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12.6.2 Setting Breakpoints on DECthreads Tasking Constructs 

You can set a breakpoint on a thread start routine. The breakpoint will trigger 
just before the start routine begins execution. In Example 12-1, this type of 
breakpoint would be set as follows: 

DBG> SET BREAK worker_routine 

Unlike Ada tasks, you cannot specify the body of a DECthreads task by name but 
the start routine is similar. 

Specifying a WHEN clause with the SET BREAK command ensures that you 
catch the point at which a particular thread begins execution. For example: 

DBG> SET BREAK worker routine - 
__DBG> WHEN (%CALLER_TASK = I TASK 4) 

In Example 12—1, this conditional breakpoint would trigger when the second 
worker thread begins executing its start routine. 

Other useful places to set breakpoints are just prior to and immediately after 
condition waits, joins, and locking of mutexes. You can set such breakpoints by 
specifying either a line number or the routine name. 

12.6.3 Setting Breakpoints on Ada Task Bodies, Entry Calls, and Accept 
Statements 

You can set a breakpoint on a task body by using one of the following two forms 
to refer to the task body (see Section 12.3.2): 

task-type-identifier$TASK_BODY 

task-identifier$TASK_BODY 

For example, the following command sets a breakpoint on the body of task 
CHILD. This breakpoint is triggered just before the elaboration of the task’s 
declarative part (also called the task’s activation). 

DBG> SET BREAK CHILD$TASK_BODY 

Note that CHILD$TASK_BODY is a name for the address of the first instruction 
the task will execute. It is meaningful to set a breakpoint on an instruction, 
and hence on this name. However, you must not name the task object (for 
example, CHILD) in a SET BREAK command. The task-object name designates 
the address of a data item (the 32-bit task value). Just as it is erroneous to set 
a breakpoint on an integer object, it is erroneous to set a breakpoint on a task 
object. 

You can monitor the execution of communicating tasks by setting breakpoints or 
tracepoints on entry calls and accept statements. 

--- Note__ 

Ada task entry calls are not the same as subprogram calls because task 
entry calls are queued and may not execute right away. If you use the 
STEP command to move execution into a task entry call, the results 
might not be what you expect. 


There are several points in and around an accept statement where you might 
want to set a breakpoint or tracepoint. For example, consider the following 
program segment, which has two accept statements for the same entry 
RENDEZVOUS: 
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8 task body TWO_ACCEPTS is 

9 begin 

10 for I in 1..2 loop 

11 select 

12 accept RENDEZVOUS do 

13 PUT_LINE("This is the first accept statement"); 

14 end RENDEZVOUS; 

15 or 

16 terminate; 

17 end select; 

18 end loop; 

19 accept RENDEZVOUS do 

20 PUT LINE("This is the second accept statement"); 

21 end RENDEZVOUS; 

22 end TWO_ACCEPTS; 

You can set a breakpoint or tracepoint in the following places in this example: 

• At the start of an accept statement (line 12 or 19). By setting a breakpoint 
or tracepoint here, you can monitor when execution reaches the start of the 
accept statement, where the accepting task might become suspended before a 
rendezvous actually occurs. 

• At the start of the body (sequence of statements) of an accept statement (line 
13 or 20). By setting a breakpoint or tracepoint here, you can monitor when 
a rendezvous has begun—that is, when the accept statement actually begins 
execution. 

• At the end of an accept statement (line 14 or 21). By setting a breakpoint or 
tracepoint here, you can monitor when the rendezvous has completed, and 
execution is about to switch back to the caller task. 

To set a breakpoint or tracepoint in and around an accept statement, you can 
specify the associated line number. For example, the following command sets a 
breakpoint on the start and also on the body of the first accept statement in the 
preceding example: 

DBG> SET BREAK %LINE 12, %LINE 13 

To set a breakpoint or a tracepoint on an accept statement body, you can also use 
the entry name (specifying its expanded name to identify the task body where the 
entry is declared). For example: 

DBG> SET BREAK TWO_ACCEPTS$TASK_BODY.RENDEZVOUS 

If there is more than one accept statement for an entry, the debugger treats the 
entry as an overloaded name. In other words, the debugger issues a message 
indicating that the symbol is overloaded, and you must use the SHOW SYMBOL 
command to identify the overloaded names that have been assigned by the 
debugger. For example: 

DBG> SHOW SYMBOL RENDEZVOUS 

overloaded symbol TEST.TWO_ACCEPTS$TASK_BODY.RENDEZVOUS 

overloaded instance TEST.TWO_ACCEPTS$TASK_BODY.RENDEZVOUS_l 
overloaded instance TEST.TW0_ACCEPTS$TASK_B0DY.RENDEZV0US_2 

Overloaded names have an integer suffix preceded by two underscores. For more 
information on overloaded names, see Section E.1.15. 

To determine which of these overloaded names is associated with a particular 
accept statement, use the EXAMINE/SOURCE command. For example: 
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DBG> EXAMINE/SOURCE TWO_ACCEPTS$TASK BODY.RENDEZVOUS 1 
module TEST_ACCEPTS — 

12: accept RENDEZVOUS do 

DBG> EXAMINE/SOURCE TWO_ACCEPTS$TASK BODY.RENDEZVOUS 2 
module TEST_ACCEPTS — 

19: accept RENDEZVOUS do 

In the following example, when the breakpoint triggers, the caller task is 
evaluated (see Section 12.3.4 for information about the symbol %CALLER_TASK): 

DBG> SET BREAK TWO_ACCEPTS$TASK_BODY.RENDEZVOUS 2 - 
_DBG> DO (EVALUATE %CALLER_TASK) — 

The following breakpoint triggers only when the caller task is %TASK 2: 

DBG> SET BREAK TWO_ACCEPTS$TASK_BODY.RENDEZVOUS 2 - 
_DBG> WHEN (%CALLER_TASK = %TASK 2) — 

If the calling task has more than one entry call to the same accept statement, you 
can use the SHOW TASK/CALLS command to identify the source line where the 
entry call was issued. For example: 

DBG> SET BREAK TWO_ACCEPTS$TASK_BODY.RENDEZVOUS 2 - 
_DBG> DO (SHOW TASK/CALLS %CALLER_TASK) — 

12.6.4 Monitoring Task Events 

The SET BREAK/EVENT and SET TRACE/EVENT commands enable you to 
set breakpoints and tracepoints that are triggered by task and exception events. 
For example, the following command sets tracepoints that trigger whenever task 
CHILD or %TASK 2 makes a transition to the RUN state: 

DBG> SET TRACE/EVENT=RUN CHILD,%TASK 2 

When a breakpoint or tracepoint is triggered as a result of an event, the debugger 
identifies the event and gives additional information. 

The following tables list the event-name keywords that you can specify with the 
SET BREAK/EVENT and SET TRACE/EVENT commands: 

• Table 12-6 lists the generic language-independent events common to all 
tasks. 

• Table 12-7 lists the events specific to DECthreads tasks. 

• Table 12-8 lists the events specific to Ada tasks. 


Table 12-6 Generic Low-Level Task Scheduling Events 


Event Name 

Description 

RUN 

Triggers when a task is about to run. 

PREEMPTED 

Triggers when a task is being preempted from the RUN state and 
its state changes to READY. (See Table 12-3.) 

ACTIVATING 

Triggers when a task is about to begin its execution. 

SUSPENDED 

Triggers when a task is about to be suspended. 


■ 
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Table 12-7 DECthreads-Specific Events 


Event Name 

Description 

HANDLED 

Triggers when an exception is about to be handled in 
some TRY block. 

TERMINATED 

Triggers when a task is terminating (including by alert 
or exception). 

EXCEPTION_TERMINATED 

Triggers when a task is terminating because of an 
exception. 

FORCED_TERM 

Triggers when a task is terminating due to an alert 
operation. 

Table 12-8 Ada-Specific Events 

Event Name 

Description 

HANDLED 

Triggers when an exception is about to be handled 
in some Ada exception handler, including an others 


handler. 

HANDLED_OTHERS 

Triggers only when an exception is about to be handled 
in an others Ada exception handler. 

RENDEZVOUS.EXCEPTION 

Triggers when an exception begins to propagate out of 
a rendezvous. 

DEPENDENTSJEXCEPTION 

Triggers when an exception causes a task to wait for 


dependent tasks in some scope (includes unhandled 
exceptions, 1 which, in turn, include special exceptions 


internal to the VAX Ada run-time library; for more 
information, see the VAX Ada documentation). Often 
immediately precedes a deadlock. 

TERMINATED 

Triggers when a task is terminating, whether 
normally, by an abort statement, or by an exception. 

EXCEPTION_TERMINATED 

Triggers when a task is terminating due to an 
unhandled exception. 1 

ABORT_TERMINATED 

Triggers when a task is terminating due to an abort 
statement. 

1 An unhandled exception is an exception for which there is no handler in the current frame or for 
which there is a handler that executes a raise statement and propagates the exception to an outer 

scope. 



In the previous tables, the exception-related events are included for completeness. 
Only the task events are discussed in the following paragraphs (for more 
information about the exception events, see Section E.l.10.3). 

You can abbreviate an event name keyword to the minimum number of characters 
that make it unique. 

The event-name keywords that you can specify with the SET BREAK/EVENT 
or SET TRACE/EVENT command depend on the current event facility, which 
is either THREADS or ADA in the case of task events. The appropriate event 
facility is set automatically when you invoke the debugger. The SHOW EVENT_ 
FACILITY command identifies the facility that is currently set and lists the valid 
event name keywords for that facility (including those for the generic events). 
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Several examples follow showing the use of the /EVENT qualifier. 

DBG> SET BREAK/EVENT=PREEMPTED 
DBG> GO 

break on THREADS event PREEMPTED 

Task ITASK 4 is getting preempted by ITASK 3 


DBG> SET BREAK/EVENT=SUSPENDED 
DBG> GO 

break on THREADS event SUSPENDED 

Task ITASK 1 is about to be suspended 


DBG> SET BREAK/EVENT=TERMINATED 
DBG> GO 

break on THREADS event TERMINATED 
Task ITASK 4 is terminating normally 
DBG> 

Certain predefined event breakpoints are set automatically when you invoke the 
debugger: 

• EXCEPTION_TERMINATED event breakpoints are predefined for programs 
that call DECthreads routines. 

• EXCEPTION.TERMINATED and DEPENDENTS_EXCEPTION event 
breakpoints are predefined for Ada programs or programs that call Ada 
routines. 

Ada examples of the predefined and other types of event breakpoints follow. 

Example of EXCEPTIONTERMINATED Event 

When the EXCEPTION_TERMINATED event is triggered, it usually indicates an 
unanticipated program error. For example: 

break on ADA event EXCEPTION_TERMINATED 

Task ITASK 2 is terminating because of an exception 

IADA-F-EXCCOP, Exception was copied at a "raise;" or "accept" 

-ADA-F-EXCEPTION, Exception S0ME_ERR0R 

-ADA-F-EXCRAIPRI, Exception raised prior to PC = 00000B61 

DBG> 

Example of DEPENDENTSJEXCEPTION Event (Ada) 

For Ada programs, the DEPENDENTSJEXCEPTION event often unexpectedly 
precedes a deadlock. For example: 

break on ADA event DEPENDENTS_EXCEPTION 

Task ITASK 2 may await dependent tasks because of this exception: 
IADA-F-EXCCOP, Exception was copied at a "raise;" or "accept" 
-ADA-F-EXCEPTION, Exception SOME_ERROR 
-ADA-F-EXCRAIPRI, Exception raised prior to PC = 00000B61 

DBG> 
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Example of RENDEZVOUS_EXCEPTION Event (Ada) 

For Ada programs, the RENDEZVOUS_EXCEPTION event enables you to see an 
exception before it leaves a rendezvous (before exception information has been 
lost due to copying the exception into the calling task). For example: 

break on ADA event RENDEZVOUS_EXCEPTION 

Exception is propagating out of a rendezvous in task %TASK 2 
%ADA-F-CONSTRAINT_ERRO, CONSTRAINT_ERROR 
-ADA-I-EXCRAIPRI, Exception raised prior to PC = 00000BA6 

DBG> 

To cancel breakpoints (or tracepoints) set with the /EVENT qualifier, use the 
CANCEL BREAK/EVENT (or CANCEL TRACE/EVENT) command. Specify the 
event qualifier and optional task expression in the CANCEL command exactly as 
you did with the SET command, excluding any WHEN or DO clauses. 

You might want to set event breakpoints and tracepoints in a debugger 
initialization file for your tasking programs. For example: 

SET BREAK/EVENT=ACTIVATING 

SET BREAK/EVENT=HANDLED DO (SHOW CALLS) 

SET BREAK/EVENT=ABORT_TERMINATED DO (SHOW CALLS) 

SET BREAK/EVENT=EXCEPTION_TERM DO (SHOW CALLS) 

SET BREAK/EVENT=TERMINATED 

12.7 Additional Task-Debugging Topics 

The following sections discuss additional topics related to task debugging: 

• Deadlock 

• Automatic stack checking 

• Using Ctrl/Y 

12.7.1 Debugging Programs with Deadlock Conditions 

A deadlock is an error condition in which each task in a group of tasks is 
suspended and no task in the group can resume execution until some other task 
in the group executes. Deadlock is a typical error in tasking programs (in much 
the same way that infinite loops are typical errors in programs that use WHILE 
statements). 

A deadlock is easy to detect: it causes your program to appear to suspend, or 
hang, in midexecution. When deadlock occurs in a program that is running under 
debugger control, press Ctrl/C to interrupt the deadlock and display the debugger 
prompt. 

In general, the SHOW TASK/ALL command (see Section 12.4) or the SHOW 
TASK/STATE=SUSPENDED command is useful because it shows which tasks 
are suspended in your program and why. The command SET TASK/VISIBLE 
%NEXT_TASK is particularly useful when debugging in screen mode. It enables 
you to cycle through all tasks and display the code that each task is executing, 
including the code in which execution is stopped. 

The SHOW TASK/FULL command gives detailed task state information, 
including information about rendezvous, entry calls, and entry index values. 

The SET BREAK/EVENT or SET TRACE/EVENT command (see Section 12.6.4) 
enables you to set breakpoints or tracepoints at or near locations that might lead 
to deadlock. The SET TASK/PRIORITY and SET TASK/RESTORE commands 
enable you to see if a low-priority task that never runs is causing the deadlock. 
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Table 12—9 lists a number of tasking deadlock conditions and suggests debugger 
commands that are useful in diagnosing the cause. 


Table 12—9 Ada Tasking Deadlock Conditions and Debugger Commands for 
Diagnosing Them 


Deadlock Condition 

Debugger Commands 

Self-calling deadlock (a task calls 
one of its own entries) 

SHOW TASK/ALL 

SHOW TASK/STATE=SUSPENDED 

SHOW TASK/FULL 

Circular-calling deadlock (a task 
calls another task, which calls the 
first task) 

SHOW TASK/ALL 

SHOW TASK/STATE=SUSPENDED 

SHOW TASK/FULL 

Dynamic-calling deadlock (a 
circular series of entry calls exists, 
and at least one of the calls is a 
timed or conditional entry call in a 
loop) 

SHOW TASK/ALL 

SHOW TASK/STATE=SUSPENDED 

SHOW TASK/FULL 

Exception-induced deadlock (an 
exception prevents a task from 
answering one of its entry calls, 
or the propagation of an exception 
must wait for dependent tasks) 

SHOW TASK/ALL 

SHOW TASK/STATE=SUSPENDED 

SHOW TASK/FULL 

SET BREAK/EVENT=DEPENDENTS_EXCEPTION 
(for Ada programs) 

Deadlock due to incorrect run¬ 
time calculations for entry 
indexes, when conditions, and 
delay statements within select 
statements 

SHOW TASK/ALL 

SHOW TASK/STATE=SUSPENDED 

SHOW TASK/FULL 

EXAMINE 

Deadlock due to entries being 
called in the wrong order 

SHOW TASK/ALL 

SHOW TASK/STATE=SUSPENDED 

SHOW TASK/FULL 

Deadlock due to busy-waiting on 
a variable used as a flag that is to 
be set by a lower priority task, and 
the lower priority task never runs 
because a higher priority task is 
always ready to execute 

SHOW TASK/ALL 

SHOW TASK/STATE=SUSPENDED 

SHOW TASK/FULL 

SET TASK/PRIORITY 

SET TASK/RESTORE 


12.7.2 Automatic Stack Checking in the Debugger 

In tasking programs, an undetected stack overflow can occur in certain 
circumstances and can lead to unpredictable execution. (For more information on 
task stack overflow, see the Ada or DECthreads documentation.) The debugger 
automatically does the following stack checks to help you detect the source of 
stack overflow problems. (If the stack pointer is out of bounds, the debugger 
displays an error message.) 

• A stack check is done for the active task after a STEP command executes or 
a breakpoint triggers (see Section 12.6.1). (This check is not done if you have 
used the /SILENT qualifier with the STEP or SET BREAKPOINT command.) 

• A stack check is done for each task whose state is displayed in a SHOW 
TASK command. Thus, a SHOW TASK/ALL command automatically causes 
the stacks of all tasks to be checked. 
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The following examples show the kinds of error messages displayed by the 
debugger when a stack check fails. A warning is issued when most of the stack 
has been used up, even if the stack has not yet overflowed. 

warning: %TASK 2 has used up over 90% of its stack 

SP: 0011194C Stack top at: 00111200 Remaining bytes: 1868 

error: ITASK 2 has overflowed its stack 

SP: 0010E93C Stack top at: 00111200 Remaining bytes: -10436 

error: %TASK 2 has underflowed its stack 

SP: 7FF363A4 Stack base at: 001189FC Stack top at: 00111200 

One of the unpredictable events that can happen after a stack overflows is that 
the stack can then underflow. This arises as follows. If a task stack overflows and 
the stack pointer remains in the top guard area, the VMS operating system will 
try to signal an ACCVIO condition. However, because the top guard area is not 
a writable area of the stack, the VMS operating system cannot write the signal 
arguments for the ACCVIO. When this happens, the VMS operating system cuts 
back the stack: it causes the frame pointer and stack pointer to point to the 
base of the main program stack area, writes the signal arguments, and then 
changes the program counter to force an image exit. If a time-slice AST or other 
AST occurs at this instant, execution can resume in a different task, and for a 
while, the program might continue to execute, although not normally (the task 
whose stack overflowed might use—and overwrite—the main program stack). The 
debugger stack checks help you to detect this situation. If you step into a task 
whose stack has been cut back by the VMS operating system, or if you use the 
SHOW TASK/ALL command at that time, the debugger issues its stack underflow 
message. 

12.7.3 Using Ctrl/Y When Debugging Ada Tasks 

Pressing Ctrl/C is the recommended method of interrupting program execution 
or a debugger command during a debugging session. This returns control to the 
debugger, whereas pressing Ctrl/Y returns control to DCL level. 

If you interrupt a task debugging session by pressing Ctrl/Y, you might have 
some problems when you then invoke the debugger at DCL level with the 
DEBUG command. In such cases, you should insert the following two lines in 
the source code at the beginning of your main program to name the VAX Ada 
predefined package CONTROL_C_INTERCEPTION: 

with CONTROL_C_INTERCEPTION; 

pragma ELABORATE(CONTROL_C_INTERCEPTION); 

For information on this package, see the VAX Ada documentation. 
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The Debugger Command Dictionary contains detailed reference information about 
all debugger commands, organized as follows: 

• Section 1 explains how to enter debugger commands. 

• Section 2 gives general information about debugger diagnostic messages. 

• Section 3 lists commands that apply only when you are using the debugger at 
a workstation running VWS (not DECwindows). 

• Section 4 contains detailed reference information about the debugger 
commands. 

1 Debugger Command Format 

You can enter debugger commands interactively at the keyboard or store them 
within a command procedure to be invoked later with the @ (Execute Procedure) 
command. 

This section gives the following information: 

• General format for debugger commands 

• Rules for entering commands interactively at the keyboard 

• Rules for entering commands in debugger command procedures 

1.1 General Format 

A command string is the complete specification of a debugger command. 
Although you can continue a command on more than one line, the term command 
string is used to define an entire command that is passed to the debugger. 

A debugger command string consists of a verb and, possibly, parameters and 
qualifiers. 

The verb specifies the command to be executed. Some debugger command strings 
might consist of only a verb or a verb pair. For example: 

DBG> GO 

DBG> SHOW IMAGE 

A parameter specifies what the verb acts on (for example, a file specification). 

A qualifier describes or modifies the action taken by the verb. Some command 
strings might include one or more parameters or qualifiers. In the follow ing 
examples, COUNT, I, J, and K, OUT2, and PROG4.COM are parameters (@ is the 
"execute procedure" command); /SCROLL and /OUTPUT are qualifiers. 

DBG> SET WATCH COUNT 
DBG> EXAMINE I,J,K 
DBG> SELECT/SCROLL/OUTPUT 0UT2 
DBG> @PR0G4.C0M 

Some commands accept optional WHEN or DO clauses. DO clauses are also used 
in some screen display definitions. 

A WHEN clause consists of the keyword WHEN followed by a conditional 
expression (within parentheses) that evaluates to true or false in the current 
language. A DO clause consists of the keyword DO followed by one or more 
command strings (within parentheses) that are to be executed in the order that 
they are listed. You must separate multiple command strings with semicolons (;). 
These points are illustrated in the next example. 
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The following command string sets a breakpoint on routine SWAP that is 
triggered whenever the value of J equals 4 during execution. When the 
breakpoint is triggered, the debugger executes the two command strings SHOW 
CALLS and EXAMINE I,K, in the order indicated. 

DBG> SET BREAK SWAP WHEN (J = 4) DO (SHOW CALLS; EXAMINE I,K) 

The debugger checks the syntax of the commands in a DO clause when it executes 
the DO clause. You can nest commands within DO clauses. 

1.2 Entering Commands at the Keyboard 

When entering a debugger command interactively at the keyboard, you can 
abbreviate a keyword (verb, qualifier, parameter) to as few characters as are 
needed to make it unique within the set of all debugger keywords. However, some 
commonly used commands (for example, EXAMINE, DEPOSIT, GO, STEP) can be 
abbreviated to their first characters. Also, in some cases, the debugger interprets 
nonunique abbreviations correctly on the basis of context. 

Pressing the Return key terminates the current line, causing the debugger to 
process it. To continue a long command string on another line, type a hyphen 
(-) before pressing Return. As a result, the debugger prompt is prefixed with an 
underscore character (_DBG>), indicating that the command string is still being 
accepted. 

You can enter more than one command string on one line by separating command 
strings with semicolons (;). 

To enter a comment (explanatory text that is recorded in a debugger log file 
but is otherwise ignored by the debugger), precede the comment text with an 
exclamation point (!). If the comment wraps to another line, start that line with 
an exclamation point. 

The command line editing functions that are available at the DCL prompt 
are also available at the debugger prompt, including command recall with the up 
arrow and down arrow keys. For example, pressing the left arrow and right arrow 
keys moves the cursor one character to the left and right, respectively; pressing 
Ctrl/H or Ctrl/E moves the cursor to the start or end of the line, respectively; 
pressing Ctrl/U deletes all the characters to the left of the cursor, and so on. 

To interrupt a command that is being processed by the debugger, press Ctrl/C. 
(See the description of Ctrl/C in the command dictionary.) 

1.3 Entering Commands in Command Procedures 

To maximize legibility, it is best not to abbreviate command keywords in a 
command procedure. Do not abbreviate command keywords to less than four 
significant characters (not counting the negation /NO ... ), to avoid potential 
conflicts in future releases. 

Start a debugger command line at the left margin. (Do not start a command line 
with a dollar sign ($) as you do when writing a DCL command procedure). 

The beginning of a new line ends the previous command line (the end-of-file 
character also ends the previous command line). To continue a command string 
on another line, type a hyphen (-) before starting the new line. 

You can enter more than one command string on one line by separating command 
strings with semicolons (;). 
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To enter a comment (explanatory text that does not affect the execution of the 
command procedure), precede the comment text with an exclamation point (!). If 
the comment wraps to another line, start that line with an exclamation point. 

2 Debugger Diagnostic Messages 

The following example shows the elements of a debugger diagnostic message: 
%DEBUG-W-NOSYMBOL, symbol 'X' is not in the symbol table 

O © 0 © 

DBG> 

O The facility name (DEBUG). 

© The severity level (W, in this example). 

© The message identifier (NOSYMBOL, in this example). The message 
identifier is an abbreviation of the message text. 

© The message text. 

The identifier enables you to find the explanation for a diagnostic message from 
the debugger’s online help (and the action you need to take, if any). 

To get online help about a debugger message, use the following general command 
format: 

HELP MESSAGES message-identifier 

The possible severity levels for diagnostic messages are as follows: 

S (success) 

I (informational) 

W (warning) 

E (error) 

F (fatal, or severe error) 

Success and informational messages inform you that the debugger has performed 
your request. 

Warning messages indicate that the debugger might have performed some, but 
not all, of your request and that you should verify the result. 

Error messages indicate that the debugger could not perform your request, but 
that the state of the debugging session was not changed. The only exceptions are 
if the message identifier was DBGERR or INTERR. These identifiers signify an 
internal debugger error, and you should submit a Software Performance Report 
(SPR) in such cases. 

Fatal messages indicate that the debugger could not perform your request and 
that the debugging session is in an indeterminate state from which you cannot 
recover reliably. Typically, the error ends the debugging session. 

3 Commands Recognized Only on Workstations Running VWS 

The following commands are recognized only when you are us in g the debugger at 
a workstation running VWS (not DECwindows): 

• SET MODE [NOJSEPARATE 

• SET PROMPT/[N0]P0P 

See the descriptions of these commands in the command dictionary in Section 4. 
All of the other debugger commands apply to workstations as well as terminals. 
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4 Debugger Command Dictionary 

The Debugger Command Dictionary describes each of the debugger commands in 
detail. Commands are listed alphabetically. The following information is provided 
for each command: command description, format, parameters, qualifiers, and one 
or more examples. See the preface of this manual for documentation conventions. 
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@ (Execute Procedure) 


Executes a debugger command procedure. 


Format 

@file-spec [parameter^ ... ]] 


Parameters 

file-spec 

Specifies the command procedure to be executed. For any part of the full 
file specification that is not provided, the debugger uses the file specification 
established with the last SET ATSIGN command, if any. If the missing part 
of the file specification was not established by a SET ATSIGN command, the 
debugger assumes SYS$DISK:[ JDEBUG.COM as the default file specification. 
You can specify a logical name. 

parameter 

Specifies a parameter that is passed to the command procedure. The parameter 
can be an address expression, a value expression in the current language, or 
a debugger command; the command must be enclosed within quotation marks 
( "). Unlike with DCL, you must separate parameters by commas. Also, you 
can pass as many parameters as there are formal parameter declarations within 
the command procedure. For more information about passing parameters to 
command procedures, see the DECLARE command description. 


Description 

A debugger command procedure can contain any debugger commands, including 
another @ command. The debugger executes commands from the command 
procedure until it reaches an EXIT or QUIT command or the end of the file. At 
that point, the debugger returns control to the command stream that invoked 
the command procedure. A command stream can be the terminal, an outer 
(containing) command procedure, a DO clause in a command such as SET 
BREAK, or a DO clause in a screen display definition. 

By default, commands read from a command procedure are not echoed. If you 
enter the SET OUTPUT VERIFY command, all commands read from a command 
procedure are echoed on the current output device, as specified by DBG$OUTPUT 
(the default output device is SYS$OUTPUT). 

For information about passing parameters to command procedures, see the 
DECLARE command description. 

Related commands: 

DECLARE 

(SET,SHOW) ATSIGN 
SET OUTPUT [NO]VERIFY 
SHOW OUTPUT 
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Example 

DBG> SET ATSIGN USER:[JONES.DEBUG].DBG 

DBG> SET OUTPUT VERIFY 

DBG> 0CHECKOUT 

IDEBUG-I-VERIFYICF, entering command procedure CHECKOUT 

SET MODULE/ALL 

SET BREAK SUB1 

GO 

break at routine PROG5\SUB2 

EXAMINE X 

PROG5\SUB2\X: 376 


IDEBUG-I-VERIFYICF, exiting command procedure MAIN 

DBG> 

In this example, the SET ATSIGN command establishes that debugger command 
procedures are, by default, in USER:[JONES.DEBUG] and have a file type 
of DBG. The ©CHECKOUT command executes the command procedure 
USER:[JONES.DEBUG]CHECKOUT.DBG. Commands contained within the 
command procedure are echoed because the SET OUTPUT VERIFY command 
was entered. 
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ATTACH 

Passes control of your terminal from the current process to another process. 

Format 

ATTACH process-name 

Parameters 

process-name 

Specifies the process to which your terminal is to be attached. The process 
must already exist before you try to attach to it. If the process name contains 
nonalphanumeric or space characters, you must enclose it in quotation marks 
("). 

Description 

The ATTACH command enables you to go back and forth between a debugging 
session and your command interpreter, or between two debugging sessions. To 
do so, you must first use the SPAWN command to create a subprocess (see the 
description of the SPAWN command); you can then attach to it whenever you 
want. To return to your original process with minimal system overhead, use 
another ATTACH command. 

Related command: SPAWN. 

Examples 


1. DBG> SPAWN 

$ ATTACH JONES 

IDEBUG-I-RETURNED, control returned to process JONES 
DBG> ATTACH JONES 1 
$ 

In this example, the series of commands creates a subprocess named 
JONES_l from the debugger (currently running in the process JONES) and 
then attaches to that subprocess. 

2. DBG> ATTACH "Alpha One" 

$ 

This example illustrates use of quotation marks to enclose a process name 
that contains a space character. 


CD-9 






Debugger Command Dictionary 
CALL 


CALL 

Format 

Parameters 


Calls a routine that was linked with your program. 


CALL routine-name [(argument^ ...])] 


routine-name 

Specifies the name or the memory address of the routine to be called. 

argument 

Specifies an argument that is required by the routine. Arguments can be passed 

by address (the default), by descriptor, by reference, and by value, as follows: 

%ADDR Passes the argument by address. This is the default. The format is 
as follows: 

CALL routine-name (%ADDR address-expression) 

The debugger evaluates the address expression and passes that 
address to the routine specified. For simple variables (such as X), 
the address of X is passed into the routine. This passing mechanism 
is how FORTRAN implements ROUTINE(X). In other words, for 
named variables, using %ADDR corresponds to a call by reference in 
FORTRAN. For other expressions, however, you must use the %REF 
function to call by reference. For complex or composite variables 
(such as arrays, records, and access types), the address is passed 
when you specify %ADDR, but the called routine might not handle 
the passed data properly. Do not specify a literal value (a number or 
an expression composed of numbers) when using %ADDR. 

%DESCR Passes the argument by descriptor. The format is as follows: 


CALL routine-name (%DESCR language-expression) 

The debugger evaluates the language expression and builds a VAX- 
standard descriptor to describe the value. The descriptor is then 
passed to the routine you named. You would use this technique to 
pass strings to a FORTRAN routine. 

%REF Passes the argument by reference. The format is as follows: 

CALL routine-name (%REF language-expression) 

The debugger evaluates the language expression and passes 
a pointer to the value, into the called routine. This passing 
mechanism corresponds to the way FORTRAN passes the result 
of an expression. 

%VAL Passes the argument by value. The format is as follows: 


CALL routine-name (%VAL language-expression) 

The debugger evaluates the language expression and passes the 
value directly to the called routine. 
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Qualifiers 

/AST (default) 

/NOAST 

Controls whether the delivery of asynchronous system traps (ASTs) is enabled or 
disabled during the execution of the called routine. The /AST qualifier specifies 
that ASTs can be delivered, if delivery of ASTs was enabled before the CALL 
command was entered (that is, unless you previously entered the DISABLE AST 
command). The /NOAST qualifier specifies that ASTs cannot be delivered. 

/SAVE_VECTOR_STATE 
/NOSAVE_VECTOR_STATE (default) 

Applies to vectorized programs. 

Controls whether the current state of the vector processor is saved and then 
restored when a routine is called with the CALL command. 

The state of the vector processor comprises the following: 

• The values of the vector registers (VO to V15) and the vector control registers 
(VCR, VLR, and VMR) 

• Any vector exception (an exception caused by the execution of a vector 
instruction) that might be pending delivery 

When you use the CALL command to execute a routine, execution of the routine 
might change the state of the vector processor as follows: 

• By changing the values of vector registers or vector control registers 

• By causing a vector exception 

• By causing the delivery of a vector exception that was pending when the 
CALL command was issued 

The /SAVE_VECTOR_STATE qualifier specifies that after the called routine has 
completed execution, the debugger restores the state of the vector processor that 
exists before the CALL command is issued. This ensures that, after the called 
routine has completed execution: 

• Any vector exception that was pending delivery before the CALL command 
was issued is still pending delivery 

• No vector exception that was triggered during the routine call is still pending 
delivery 

• The values of the vector registers are identical to their values before the 
CALL command was issued 

The /NOSAVE_VECTOR_STATE qualifier, which is the default, specifies that the 
state of the vector processor that exists before the CALL command is issued is 
not restored by the debugger after the called routine has completed execution. In 
this case, the state of the vector processor after the routine call depends on the 
effect (if any) of the called routine. 

The /[NO]SAVE_VECTOR_STATE qualifiers have no effect on the VAX general 
registers. The values of these registers are always saved and restored when you 
execute a routine with the CALL command. 
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Description 

The CALL command is one of the four debugger commands that can be used to 
execute your program (the others are GO, STEP, and EXIT). The CALL command 
enables you to execute a routine independently of the normal execution of your 
program. The CALL command executes a routine whether or not your program 
actually includes a call to that routine, as long as the routine was linked with 
your program. 

When you enter a CALL command, the debugger takes the following action. (See 
the qualifier descriptions for additional information.) 

1. Saves the current values of the VAX general registers. 

2. Constructs an argument list. 

3. Executes a call to the routine specified in the command and passes any 
arguments. 

4. Executes the routine. 

5. Displays the value returned by the routine in register RO. By VMS 
convention, after a called routine has executed, register RO contains the 
fiinction return value (if the routine is a function) or the procedure completion 
status (if the routine is a procedure that returns a status value). If a called 
procedure does not return a status value or function value, the value in RO 
might be meaningless, and the "value returned" message can be ignored. 

6. Restores the values of the general registers to the values they had just before 
the CALL command was executed. 

7. Issues the prompt. 

The debugger assumes that the called routine conforms to the VMS procedure 
calling standard (see the VAX Architecture Handbook). However, the debugger 
does not know about all the argument-passing mechanisms for all supported 
languages. Therefore, you might need to specify how to pass parameters—for 
example, use CALL SUB1(%VAL X) rather than CALL SUB1(X). See your 
language documentation for complete information about how arguments are 
passed to routines. 

If you use the CALL command to call a routine that changes the value of a passed 
parameter and returns a new value, the returned value might be unreliable. 

A common debugging technique at an exception breakpoint (resulting from a SET 
BREAK/EXCEPTION or STEP/EXCEPTION command) is to call a dump routine 
with the CALL command. When you enter the CALL command at an exception 
breakpoint, any breakpoints, tracepoints, or watchpoints that were previously set 
within the called routine are disabled temporarily so that the debugger does not 
lose the exception context. However, such eventpoints are active if you enter the 
CALL command at a location other than an exception breakpoint. 

When an exception breakpoint is triggered, execution is suspended before any 
application-declared condition handler is invoked. At an exception breakpoint, 
entering a GO or STEP command after executing a routine with the CALL 
command causes the debugger to resignal the exception (see the descriptions of 
the GO and STEP commands). 
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If you are using the multiprocess debugging configuration to debug a multiprocess 
program (if the logical name DBG$PROCESS has the value MULTIPROCESS), 
note the following additional points: 

• The CALL command is executed in the context of the visible process, but 
images in any other processes that are not on hold (through a SET PROCESS 
/HOLD command) are also allowed to execute. If you use the DO command 
to broadcast a CALL command to one or more processes, the CALL command 
is executed in the context of each specified process that is not on hold, but 
images in any other processes that are not on hold are also allowed to execute. 
In all cases, a hold condition in the visible process is ignored. 

• After execution is started, the way in which it continues depends on whether 
the SET MODE [NOJINTERRUPT command was entered. By default (SET 
MODE INTERRUPT), execution continues until it is suspended in any 
process. At that point, execution is interrupted in any other processes that 
were executing images, and the debugger prompts for input. 

Related commands: 

GO 

EXIT 

DO 

SET PROCESS 

SET MODE [NOJINTERRUPT 

SET VECTOR.MODE [NOJSYNCHRONIZED 

STEP 

SYNCHRONIZE VECTOR.MODE 


Examples 

1. DBG> CALL SUB1 (X) 
value returned is 19 
DBG> 

This command calls the routine SUB1, passing the address of X as the 
required parameter (by default, the address of the argument specified is 
passed). The routine is a function whose returned value is 19. 

2. DBG> CALL SUB(%REF 1) 
value returned is 1 
DBG> 

This command passes a pointer to a memory location containing the numeric 
literal 1, into the routine SUB. 

3. DBG> SET MODULE SHARE$LIBRTL 
DBG> CALL LIB$SHOW_VM 

1785 calls to LIB$GET_VM, 284 calls to LIB$FREE_VM, 122216 bytes 
still allocated, value returned is 00000001 
DBG> 

This example shows how you could call the run-time library routine 
LIB$SHOW_VM (in the shareable image LIBRTL) to display memory 
statistics. The SET MODULE command makes the universal symbols 
(routine names) in LIBRTL visible in the main image. See the description of 
the /SHARE qualifier of the SHOW MODULE command for more information 
about this subject. 
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SUBROUTINE CHECK_TEMP(TEMPERATURE,ERROR_MESSAGE) 

REAL TOLERANCE /4.7/ 

REAL TARGET_TEMP /92.0/ 

CHARACTER*(*) ERROR_MESSAGE 

IF (TEMPERATURE .GT. (TARGET_TEMP + TOLERANCE)) THEN 
TYPE *,'Input temperature out of rangeTEMPERATURE 
TYPE *,ERROR_MESSAGE 
ELSE 

TYPE *,'Input temperature in rangeTEMPERATURE 
END IF 
RETURN 
END 

DBG> CALL CHECK_TEMP(%REF 100.0, %DESCR 'TOLERANCE-CHECK 1 FAILED') 

Input temperature out of range: 100.0000 
TOLERANCE-CHECK 1 FAILED 
value returned is 0 

DBG> CALL CHECK_TEMP(%REF 95.2, %DESCR 'TOLERANCE-CHECK 2 FAILED') 

Input temperature in range: 95.2000 

value returned is 0 

DBG> 

In this example, the source code is that of a FORTRAN routine (CHECK_ 
TEMP) that accepts two parameters, TEMPERATURE (a real number) and 
ERROR_MESSAGE (a string). Depending on the value of the temperature, 
the routine prints different output. Each of the two CALL commands passes 
a temperature value (by reference) and an error message (by descriptor). 
Because this routine does not have a formal return value, the value returned 
is undefined, in this case, 0. 
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CANCEL ALL 

Cancels all breakpoints, tracepoints, and watchpoints. Restores the scope and 
type to their default values. Restores the line, symbolic, and G_Float modes 
established with the SET MODE command to their default values. 

Format 

CANCEL ALL 

Qualifiers 

/PREDEFINED 

Cancels all predefined (but no user defined) breakpoints, tracepoints, and 
watchpoints. 

/USER 

Cancels all user defined (but no predefined) breakpoints, tracepoints, and 
watchpoints. CANCEL ALL/USER is assumed by default unless you specify 
/PREDEFINED. 


Description 

The CANCEL ALL command performs the followings steps: 

• Cancels all breakpoints, tracepoints, and watchpoints. This is equivalent to 
entering the CANCEL BREAK/ALL, CANCEL TRACE/ALL, and CANCEL 
WATCH/ALL commands. Depending on the type of program (for example 
Ada, multiprocess), certain predefined breakpoints or tracepoints might 

be set automatically when you invoke the debugger. By default (CANCEL 
ALL/USER), only user defined breakpoints, tracepoints, and watchpoints are 
canceled—those that were previously set explicitly with the SET BREAK, 
SET TRACE, and SET WATCH commands. If you specify /PREDEFINED but 
not /USER, all predefined (but no user defined) breakpoints, tracepoints, and 
watchpoints are canceled. If you specify both /PREDEFINED and /USER, all 
predefined and user defined breakpoints, tracepoints, and watchpoints are 
canceled. 

See Section 9.3.2 for information about predefined breakpoints associated 
with Ada tasking exception events. See Chapter 10 for information about 
predefined tracepoints associated with multiprocess programs. 

• Restores the scope search list to its default value (0,1,2, .. . ,n). This is 
equivalent to entering the CANCEL SCOPE command. 

• Restores the data type for memory locations that are associated with a 
compiler generated type to the associated type. Restores the type for locations 
that are not associated with a compiler generated type to "longword integer". 
This is equivalent to entering the CANCEL TYPE/OVERRIDE and SET 
TYPE LONGWORD commands. 

• Restores the line, symbolic, and G_Float modes established with the SET 
MODE command to their default values. This is equivalent to entering the 
following command: 

DBG> SET MODE LINE,SYMBOLIC,NOG FLOAT 
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The CANCEL ALL command does not affect the current language setting or 
modules included in the run-time symbol table. 

Related commands: 

CANCEL BREAK 
CANCEL TRACE 
CANCEL TYPE/OVERRIDE 
CANCEL SCOPE 
CANCEL WATCH 
(SET,CANCEL) MODE 
SET TYPE 

Examples 

1. DBG> CANCEL ALL 

This command cancels all user defined breakpoints, tracepoints, and 
watchpoints and restores scopes, types, and some modes to their default 
values. In this example, there are no predefined breakpoints, tracepoints, or 
watchpoints. 

2. DBG> CANCEL ALL 

IDEBUG-I-PREDEPTNOT, predefined eventpoint(s) not canceled 
DBG> 

This command cancels all user defined breakpoints, tracepoints, and 
watchpoints and restores scopes, types, and some modes to their default 
values. In this example, there are some predefined breakpoints, tracepoints, 
or watchpoints, and these are not canceled by default. 

3. DBG> CANCEL ALL/PREDEFINED 

This command cancels all predefined breakpoints, tracepoints, and 
watchpoints and restores scopes, types, and some modes to their default 
values. No user defined breakpoints, tracepoints, or watchpoints are affected. 
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CANCEL BREAK 


Cancels a breakpoint. 

Format 

CANCEL BREAK [address-expression[, ... ]] 

Parameters 

address-expression 

Specifies a breakpoint to be canceled. Do not use the asterisk (*) wildcard 
character. Instead, use the /ALL qualifier. Do not specify an address expression 
when using any of the qualifiers except for /EVENT, /PREDEFINED, or /USER. 

Qualifiers 

/ACTIVATING 

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 

Cancels the effect of a previous SET BREAK/ACTIVATING command. Do not 
specify an address expression with /ACTIVATING. 

/ALL 

By default, cancels all user-defined breakpoints. When used with /PREDEFINED, 
cancels all predefined breakpoints but no user-defined breakpoints. Specify both 
/USER and /PREDEFINED to cancel all breakpoints. Do not specify an address 
expression with /ALL. 

/BRANCH 

Cancels the effect of a previous SET BREAK/BRANCH command. Do not specify 
an address expression with /BRANCH. 

/CALL 

Cancels the effect of a previous SET BREAK/CALL command. Do not specify an 
address expression with /CALL. 

/EVENT=event-name 

Cancels the effect of a previous SET BREAK/EVENT=ei>enf-name command. 
Specify the event name (and address expression, if any) exactly as it was specified 
with the SET BREAK/EVENT command. 

To identify the current event facility and the associated event names, use the 
SHOW EVENT_FACILITY command. 

/EXCEPTION 

Cancels the effect of a previous SET BREAK/EXCEPTION command. Do not 
specify an address expression with /EXCEPTION. 

/INSTRUCTION 

Cancels the effect of a previous SET BREAK/INSTRUCTION command. Do not 
specify an address expression with /INSTRUCTION. 
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/ LINE 

Cancels the effect of a previous SET BREAK/LINE command. Do not specify an 
address expression with /LINE. 

/PREDEFINED 

Cancels a specified predefined breakpoint without affecting any user defined 
breakpoints. When used with /ALL, cancels all predefined breakpoints. 

/TERMINATING 

Cancels the effect of a previous SET BREAK/TERMINATING command. Do not 
specify an address expression with /TERMINATING. 

/USER 

Cancels a specified user-defined breakpoint without affecting any predefined 
breakpoints. When used with /ALL, cancels all user defined breakpoints. 
CANCEL BREAK/USER is assumed by default unless you specify 
/PREDEFINED. 

/VECTORJNSTRUCTION 

Cancels the effect of a previous SET BREAK/VECTOR_INSTRUCTION command. 
Do not specify an address expression with /VECTORJNSTRUCTION. 

Description 

Breakpoints can be user defined or predefined. User defined breakpoints are 
those that you set explicitly with the SET BREAK command. Predefined 
breakpoints, which depend on the type of program you are debugging (for 
example, Ada or multiprocess), are established automatically when you invoke 
the debugger. Use the SHOW BREAK command to identify all breakpoints that 
are currently set. Any predefined breakpoints are identified as such. 

User-defined and predefined breakpoints are set and canceled independently. 

For example, a location or event can have both a user defined and a predefined 
breakpoint. Canceling the user defined breakpoint does not affect the predefined 
breakpoint, and conversely. 

To cancel only user defined breakpoints, do not specify /PREDEFINED with the 
CANCEL BREAK command (/USER is the default). To cancel only predefined 
breakpoints, specify /PREDEFINED but not /USER. To cancel both user defined 
and predefined breakpoints, specify both /USER and /PREDEFINED. 

In general, the effect of the CANCEL BREAK command is symmetrical with 
that of the SET BREAK command (even though the SET BREAK command 
is used only with user defined breakpoints). Thus, to cancel a breakpoint 
that was established at a specific location, specify that same location (address 
expression) with the CANCEL BREAK command. To cancel breakpoints that 
were established on a class of instructions or events, specify the class of 
instructions or events with the corresponding qualifier (for example, /LINE, 
/BRANCH, /ACTIVATING, /EVENT=, and so on). See the qualifier descriptions 
for more specific information. 

Related commands: 

CANCEL ALL 
(SET,SHOW) BREAK 
(SET,SHOW) EVENTJFACILITY 
(SET,SHOW,CANCEL) TRACE 
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Examples 

1. DBG> CANCEL BREAK MAIN\LOOP+10 

This command cancels the user defined breakpoint set at the address 
expression MAINXLOOP+IO. 

2. DBG> CANCEL BREAK/ALL 

This command cancels all user defined breakpoints. 

3. DBG> CANCEL BREAK/ALL/USER/PREDEFINED 

This command cancels all user defined and predefined breakpoints. 

4. DBG_1> CANCEL BREAK/ACTIVATING 

This command cancels a previous user defined SET BREAK/ACTIVATING 
command. As a result, the debugger does not suspend execution when a new 
process is brought under debugger control. 

5. DBG> CANCEL BREAK/EVENT=EXCEPTION_TERMINATED/PREDEFINED 

This command cancels the predefined breakpoint that is set on task 
terminations due to unhandled exceptions. This breakpoint is predefined 
for Ada programs and programs that call Ada or DECthreads routines. 
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CANCEL DISPLAY 


Permanently deletes a screen display. 

Format 

CANCEL DISPLAY [display-name[, ... ]] 


Parameters 


display-name 

Specifies the name of a display to be canceled. Do not specify 
display, which cannot be canceled. Do not use the asterisk (*) 
Instead, use the /ALL qualifier. Do not specify a display name 


the PROMPT 
wildcard character, 
with /ALL. 


Qualifiers 

/ALL .. . 

Cancels all displays, except for the PROMPT display. Do not specify a display 

name with /ALL. 

/SUFFIX[=process-identifier-type] 

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). Use this qualifier only directly after a display name. 

Appends a process-identifying suffix to a display name. The suffix denotes the 
visible process at the time the command was issued. This qualifier is used 
primarily in command procedures when specifying display definitions or key 
definitions that are bound to display definitions. 

Use any of the following process-identifier-type keywords: 

PROCESS_NAME The display-name suffix is the VMS process name. 

PROCESS_NUMBER The display-name suffix is the process number (as shown 

in a SHOW PROCESS display). 

PROCESS_PID The display-name suffix is the VMS process 

identification number (PID). 

If you specify /SUFFIX without a process-identifier-type keyword, the process 
identifier type used for the display-name suffix is, by default, the same as that 
used for the prompt suffix (see SET PROMPT/SUFFIX). 


Description 

When a display is canceled, its contents are permanently lost, it is deleted from 
the display list, and all the memory that was allocated to it is released. 

You cannot cancel the PROMPT display. 

Related commands: 

(SET,SHOW) DISPLAY 

(SET,SHOW,CANCEL) WINDOW 
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CANCEL DISPLAY 


Examples 

1. DBG> CANCEL DISPLAY SRC2 

This command permanently deletes display SRC2. 

2. DBG> CANCEL DISPLAY/ALL 

This command permanently deletes all displays, except for the PROMPT 
display. 
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CANCEL IMAGE 

Deletes symbol table information for a shareable image. 


Format 

CANCEL IMAGE [image-name[, ... ]] 

Parameters 

image-name 

Specifies a previously set shareable image to be canceled. Do not specify the main 
image, which cannot be canceled. Do not use the asterisk (*) wildcard character. 
Instead, use the /ALL qualifier. Do not specify an image name with /ALL. 

Qualifiers 

/ALL 

Specifies that all shareable images except the main image are to be canceled. Do 
not specify an image name with /ALL. 

Description 

The CANCEL IMAGE command deallocates the data structures previously built 
to debug a shareable image by a SET IMAGE command. Use the CANCEL 
IMAGE command if the debugger performance has slowed down because of 
many images and modules being set. You can also use the CANCEL MODULE 
command to delete only certain modules from an image’s run-time symbol table 
(RST) without canceling the entire image. Also, if dynamic mode is enabled (this 
is the default), you can disable it with the SET MODE NODYNAMIC command. 
As a result, the debugger does not set images or modules automatically. 

If the current image (the image last set with the SET IMAGE command) is 
canceled, the main image (the image containing the image transfer address) 
becomes the current image. 

Related commands: 

(SET,SHOW) IMAGE 

SET MODE [NOIDYNAMIC 

(SET,SHOW,CANCEL) MODULE 

Example 

DBG> CANCEL IMAGE SHARE2,SHARE3 

T his command cancels shareable images SHARE2 and SHARE3. If either of 
these was the current image, the main image becomes the current image. 
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CANCEL MODE 

Restores the line, symbolic, and G_float modes established by the SET MODE 
command to their default values. Also restores the default input/output radix. 

Format 

CANCEL MODE 


Description 

The effect of the CANCEL MODE command is equivalent to the following 
commands: 

DBG> SET MODE LINE,SYMBOLIC,NOG FLOAT 
DBG> CANCEL RADIX 

Although the same default modes apply to all languages, the default radix for 
both data entry and display is decimal for all languages except BLISS and 
MACRO. It is hexadecimal for BLISS and MACRO. 

Related commands: 

(SET,SHOW) MODE 
(SET,SHOW,CANCEL) RADIX 


Example 

DBG> CANCEL MODE 

This command restores the default radix mode and all default mode values. 
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CANCEL MODULE 


Deletes the symbol records of a module in the current image from the run-time 
symbol table (RST) for that image. 

Format 

CANCEL MODULE [module-name[, ... ]] 


Parameters 


module-name ,, 

Specifies the name of a module whose symbol records are deleted from the Kbl. 
Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. 
Do not specify a module name with /ALL. 


Qualifiers 

/ALL 

Deletes the symbol records of all modules from the RST. Do not specify a module 
name or /[NOJRELATED with /ALL. 

/RELATED (default) 

/NORELATED 

Applies to Ada programs. 

Controls whether the debugger deletes from the RST the symbol records of a 
module that is related to a specified module through a with-clause or subunit 
relationship. 

CANCEL MODULE/RELATED deletes symbol records for related modules as 
well as for those specified, but not for any module that is also related to another 
set module. The effect of CANCEL MODULE/RELATED is consistent with 
Ada’s scope and visibility rules and depends on the actual relationship between 
modules. CANCEL MODULE/NORELATED deletes symbol records only for 
modules that are specified (no symbol records are deleted for related modules). 


Description 


_Note --- 

The current image is either the main image (by default) or the image 
established as the current image by a previous SET IMAGE command. 


Use the CANCEL MODULE command if the debugger performance has slowed 
down because of many modules being set. You can also use the CANCEL IMAGE 
command to delete the symbols of an entire image (this automatically cancels 
all of the modules in that image). Also, if dynamic mode is enabled (this is the 
default), you can disable it with the SET MODE NODYNAMIC command. As a 
result, the debugger does not set modules or images automatically. 

The CANCEL MODULE command does not cancel any breakpoints, tracepoints, 
or watchpoints that are set currently. It deletes the symbolization of any 
breakpoints, tracepoints, or watchpoints associated with the canceled modules. 
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CANCEL MODULE 

See Section E.1.14 for information specific to Ada programs. 

Related commands: 

(SET,SHOW,CANCEL) IMAGE 
SET MODE [NO]DYNAMIC 
(SET,SHOW) MODULE 

Examples 

1. DBG> CANCEL MODULE SUB1 

This command deletes the symbols of module SUB1 from the RST. 

2. DBG> CANCEL MODULE/ALL 

This command deletes the symbols of all modules from the RST. 
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CANCEL RADIX 


Restores the default radix for the entry and display of integer data. 

Format 

CANCEL RADIX 


Qualifiers 


Cancels the override radix established by a previous SET RADIX/OVERRIDE 
command. This sets the current override radix to --none" and restores the output 
radix mode to the value established with a previous SET RADIX or SET RADIX 
/OUTPUT command. If you did not change the radix mode with a SET RADIX 
or SET RADIX/OUTPUT command, the CANCEL RADIX/OVERRIDE command 
restores the radix mode to its default value (decimal for all languages except 
BLISS and MACRO, hexadecimal for BLISS and MACRO). 


Description 

The CANCEL RADIX command cancels the effect of any previous SET RADIX 
and SET RADIX/OVERRIDE commands. It restores the input and output radix 
to their default value (decimal for all languages except BLISS and MACRO, 
hexadecimal for BLISS and MACRO). 

The effect of the CANCEL RADIX/OVERRIDE command is more limited and is 
explained in the description of the /OVERRIDE qualifier. 

Related commands: 

EVALUATE 
(SET,SHOW) RADIX 

Examples 

1. DBG> CANCEL RADIX 

This command restores the default input and output radix. 

2. DBG> CANCEL RADIX/OVERRIDE 

This command cancels any override radix you might have set with the SET 
RADIX/OVERRIDE command. 


CD-26 





Debugger Command Dictionary 
CANCEL SCOPE 


CANCEL SCOPE 

Restores the default scope search list for symbol lookup. 

Format 


CANCEL SCOPE 


Description 


The CANCEL SCOPE command cancels the current scope search list established 
by a previous SET SCOPE command and restores the default scope search list, 
namely 0,1,2, . . . ,n, where n is the number of calls in the call stack. 


The default scope search list specifies that, for a symbol without a pathname 
prefix, a symbol lookup such as "EXAMINE X" first looks for X in the routine 
that is currently executing (scope 0); if no X is visible there, the debugger looks in 
the caller of that routine (scope 1), and so on down the call stack; if X is not found 
in scope n, the debugger searches the rest of the run-time symbol table (RST) 
then searches the global symbol table (GST), if necessary. 

Related commands: (SET,SHOW) SCOPE. 


Example 

DBG> CANCEL SCOPE 

This command cancels the current scope. 
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CANCEL SOURCE 

Cancels a source directory search list established by a previous SET SOURCE 
command. 


Format 

CANCEL SOURCE 

Qualifiers 

/EDIT 

Applies mainly to Ada programs. 

Cancels the effect of a previous SET SOURCE/EDIT command. As a result, when 
you use the EDIT command, the debugger searches for a source file in the same 
directory that it was in at compile time. The CANCEL SOURCE/EDIT command 
does not cancel the effect of a previous SET SOURCE command. 

/MODULE=module-name 

Cancels the effect of a previous SET SOURCE/MODULE=modu/e-raame command 
in which the same module name was specified. (The module-name specifies a 
module for which a source directory search list is canceled.) As a result, the 
debugger searches for the source file of the specified module in the same directory 
that it was in at compile time. The CANCEL SOURCE/MODULE=/nodu/e-name 
command does not cancel the effect of a previous SET SOURCE command, or of 
a SET SOURCE/MODULE=moduZe-raame command in which a different module 
name was specified. 


Description 

When used without a qualifier, the CANCEL SOURCE command cancels the 
effect of a previous SET SOURCE command used without a qualifier. CANCEL 
SOURCE does not cancel the effect of a previous SET SOURCE/EDIT or SET 
SOURCE/MODULE=raodu/e-name commands. 


See the qualifier descriptions for an explanation of their effects. 

The /EDIT qualifier is needed when the files used for the display of source code 
are different from the files to be edited by means of the EDIT command. This 
is the case with Ada programs. For Ada programs, the (SET,SHOW,CANCEL) 
SOURCE commands affect the search of files used for source display (the "copied" 
source files in Ada program libraries); the (SET,SHOW,CANCEL) SOURCE/EDIT 
commands affect the search of the source files that you edit when using the 
EDIT command. If you use /MODULE with /EDIT, the effect of /EDIT is further 
qualified by /MODULE. 

See Section E.1.5 and Section E.1.6 for information specific to Ada programs. 


Related commands: 

(SET.SHOW) MAX_SOURCE_FILES 
(SET,SHOW) SOURCE 
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Example 


DBG> SHOW SOURCE 

source directory search list for COBOLTEST• 

[] 

SYSTEM::DEVICE:[PROJD] 

source directory search list for all other modules: 

[PROJA] 

[PROJB] 

[PETER.PROJC] 

DBG> CANCEL SOURCE 
DBG> SHOW SOURCE 

source directory search list for COBOLTEST: 

[] 

SYSTEM::DEVICE:[PROJD] 

DBG> CANCEL SOURCE/MODULE=COBOLTEST 
DBG> SHOW SOURCE 

no directory search list in effect 
DBG> 

cnrn^a exam P^ e > *h e CANCEL SOURCE command cancels the effect of a previous 
SET SOURCE command. It does not cancel any source directory search lists for 
specific modules. But the CANCEL SOURCE/MODULE=modu/e-na/ne command 

(m this case, COBOLTEST) cancels the source directory search list for that 
module. 
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CANCEL TRACE 

Cancels a tracepoint. 

Format 

CANCEL TRACE [address-expression[, ... ]] 


Parameters 


address-expression , 

Specifies a tracepoint to be canceled. Do not use the asterisk ( ') wildcard 
character. Instead, use the /ALL qualifier. Do not specify an address expression 
when using any of the qualifiers except for /EVENT, /PREDEFINED, or /USER. 


Qualifiers 

/ACTIVATING 

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 

Cancels the effect of a previous SET TRACE/ACTIVATING command. Do not 
specify an address expression with /ACTIVATING. 


By default, cancels all user defined tracepoints. When used with /PREDEFINED, 
cancels all predefined tracepoints but no user defined tracepoints. Specify both 
/USER and /PREDEFINED to cancel all tracepoints. Do not specify an address 
expression with /ALL. 


/BRANCH 

Cancels the effect of a previous SET TRACE/BRANCH command, 
an address expression with /BRANCH. 


Do not specify 


Cancels the effect of a previous SET TRACE/CALL command. Do not specify an 
address expression with /CALL. 

/EVENT=event-name 

Cancels the effect of a previous SET TRACE/EVENT=eyen/-name command. 
Specify the event name (and address expression, if any) exactly as they were 
specified with the SET TRACE/EVENT command. 

To identify the current event facility and the associated event names, use the 
SHOW EVENT_FACILITY command. 


/EXCEPTION , ^ 

Cancels the effect of a previous SET TRACE/EXCEPTION command. Do not 

specify an address expression with /EXCEPTION. 

/INSTRUCTION _ _ 

Cancels the effect of a previous SET TRACE/INSTRUCTION command. Do not 
specify an address expression with /INSTRUCTION. 
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/LINE 

Cancels the effect of a previous SET TRACE/LINE command, 
address expression with /LINE. 


Do not specify an 


/PREDEFINED 

Cancels a specified predefined tracepoint without affecting any user defined 
tracepomts. When used with /ALL, cancels all predefined tracepoints. 

/TERMINATING 

Cancels the effect of a previous SET TRACE/TERMINATING command. Do not 
specify an address expression with /TERMINATING. 

/USER 

Cancels a specified user defined tracepoint without affecting any predefined 

trpp a J^ Gn USed With /ALL ’ cancels a11 user defined tracepoints. CANCEL 

oKEAK/USER is assumed by default unless you specify /PREDEFINED. 

/VECTORJNSTRUCTION 

Cancels the effect of a previous SET TRACE/VECTOR_INSTRUCTION command. 
Do not specify an address expression with /VECTORJNSTRUCTION. 




Description 

Tracepoints can be user defined or predefined. User defined tracepoints are those 
that you set explicitly with the SET TRACE command. Predefined tracepoints, 
which depend on the type of program you are debugging (for example, Ada or ’ 
multiprocess), are established automatically when you invoke the debugger. Use 
the SHOW TRACE command to identify all tracepoints that are currently set. 
Any predefined tracepoints are identified as such. 

User defined and predefined tracepoints are set and canceled independently. 

For example, a location or event can have both a user defined and a predefined 
tracepoint. Canceling the user defined tracepoint does not affect the predefined 
tracepoint, and conversely. 

To cancel only user defined tracepoints, do not specify /PREDEFINED with the 
CANCEL TRACE command (/USER is the default). To cancel only predefined 
tracepoints, specify /PREDEFINED but not /USER. To cancel both user defined 
and predefined tracepoints, specify both /USER and /PREDEFINED. 

In general, the effect of the CANCEL TRACE command is symmetrical with 
that of the SET TRACE command (even though the SET TRACE command is 
used only with user defined tracepoints). Thus, to cancel a tracepoint that was 
established at a specific location, specify that same location (address expression) 
with the CANCEL TRACE command. To cancel tracepoints that were established 
on a class of instructions or events, specify the class of instructions or events 
with the corresponding qualifier (for example, /LINE, /BRANCH, /ACTIVATING, 
/EVENT=, and so on). See the qualifier descriptions for more specific information. 
Related commands: 

CANCEL ALL 

(SET,SHOW,CANCEL) BREAK 
(SET,SHOW) EVENT_FACILITY 
(SET,SHOW) TRACE 
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Examples 


1. DBG> CANCEL TRACE MAIN\LOOP+10 

This command cancels the user defined tracepoint at the location 
MAIN\ LOOP+IO. 

2. DBG> CANCEL TRACE/ALL 

This command cancels all user defined tracepoints. 

3. DBG_1> CANCEL TRACE/TERMINATING 

This command cancels a previous user defined SET TRACE/TERMINATING 
command. As a result, a tracepoint is not triggered when a process does an 
image exit. 

4 . DBG> CANCEL TRACE/EVENT=RUN ITASK 3 

T his command cancels the tracepoint that was set to trigger when task 3 
(task ID = 3) entered the RUN state. 
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CANCEL TYPE/OVERRIDE 


Cancels the override type established by a previous SET TYPE/OVERRIDE 
command. 


Format 

CANCEL TYPE/OVERRIDE 


Description 

The CANCEL TYPE/OVERRIDE command sets the current override type to 
"none". As a result, a program location associated with a compiler generated 
type is interpreted according to that type. 

Related commands: 

DEPOSIT 

EXAMINE 

(SET,SHOW) EVENT.FACILITY 


Example 

DBG> CANCEL TYPE/OVERRIDE 

This command cancels the effect of a previous SET TYPE/OVERRIDE command. 
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CANCEL WATCH 

Cancels a watchpoint. 


Format 

CANCEL WATCH [address-expression[, ... ]] 

Parameters 

address-expression . . ... 

Specifies a watchpoint to be canceled. With high-level languages, this is typically 
the name of a variable. Do not use the asterisk (*) wildcard character. Instead, 
use the /ALL qualifier. Do not specify an address expression with /ALL. 

Qualifiers 

/ALL • v /ATT 

Cancels all watchpoints. Do not specify an address expression with /ALL. 


Description 

The effect of the CANCEL WATCH command is symmetrical with the effect of 
the SET WATCH command. To cancel a watchpoint that was established at a 
specific location with the SET WATCH command, specify that same location 
with CANCEL WATCH. Thus, to cancel a watchpoint that was set on an entire 
aggregate, specify the aggregate in the CANCEL WATCH command; to cancel a 
watchpoint that was set on one element of an aggregate, specify that element in 
the CANCEL WATCH command. 

The CANCEL ALL command also cancels all watchpoints. 

Related commands: 

CANCEL ALL 

(SET,SHOW,CANCEL) BREAK 
(SET,SHOW,CANCEL) TRACE 
(SET,SHOW) WATCH 

Examples 

1. dbg> CANCEL WATCH SUB2\total 

This command cancels the watchpoint at variable TOTAL in module SUB2. 

2. DBG> CANCEL WATCH/ALL 

This command cancels all watchpoints you have set. 
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CANCEL WINDOW 


Permanently deletes a screen window definition. 

Format 


CANCEL WINDOW [window-name[, ... ]] 

Parameters 


window-name 

Specifies the name of a screen window definition to be canceled. Do not use the 
asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify a 
window name name with /ALL. 

Qualifiers 

/ALL 

Cancels all predefined and user-defined window definitions. Do not specify a 
window definition name with /ALL. 

Description 

* ™ ndow definition is canceled, you can no longer use its name in a 
DISPLAY command. The command does not affect any displays. 

Related commands: 

(SET,SHOW,CANCEL) DISPLAY 
(SET,SHOW) WATCH 

Example 

DBG> CANCEL WINDOW MIDDLE 

This command permanently deletes the screen window definition MIDDLE. 
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CONNECT 

Interrupts an image that is running without debugger control in another process 
and brings that process under debugger control. When used without a parameter, 
brings any spawned process that is waiting to connect to the debugger under 
debugger control. 

T his command applies only to a multiprocess debugging configuration (when 
DBG$PROCESS has the value MULTIPROCESS). 

Format 

CONNECT [process-spec[, ... ]] 

Parameters 

process-spec 

Specifies a process in which an image to be interrupted is running. The process 
must be in the same VMS job as the process in which the debugger was invoked. 
Use any of the following forms: 

[%PROCESS_NAME] process-name The VMS process name, if that 

name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 

[%PROCESS_NAME] "process-name" The VMS process name, if that name 

contains space or lowercase characters. 
You can also use apostrophes (') instead 
of quotation marks ("). 

%PROCESS_PID processjd The VMS process identification number 

(PID, a hexadecimal number). 


Description 

When you specify a process, the CONNECT command enables you to interrupt 
an image that is r unning without debugger control in that process and bring the 
process under debugger control. The command is useful if, for example, you run 
a debuggable image with the DCL command RUN/NODEBUG or if your program 
issues a LIB$SPAWN run-time library call or a $CREPRC system service call 
that does not invoke the debugger. 

You can bring a process under debugger control in this manner only if that 
process is in the same VMS job as the process in which the debugger was invoked, 
and only if the image was not linked with the /NOTRACEBACK qualifier. Also, 
you have full symbolic information for that image only if its modules were 
compiled and linked with the /DEBUG command qualifier. 

When the process is brought under debugger control, execution of the image is 
suspended at the point at which it was interrupted. 

When you do not specify a process, the CONNECT command brings any processes 
that are waiting to connect to your debugging session under debugger control If 
no process is waiting, you can press Ctrl/C to abort the CONNECT command. 
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By default, a tracepoint is triggered when a process is brought under debugger 
TZL™ ^defined tracepoint is equivalent to that resulting from entering 
the SET TRACE/ACTIVATING command. The process is then known to the 
debugger and can be identified in a SHOW PROCESS display. 

Related commands: 


Ctrl/Y 

(SET,SHOW,CANCEL) TRACE 


Examples 


1. dbg_i> connect 

This command brings any processes that are waiting to be connected to the 
debugger under debugger control. 

2. DBG_1> CONNECT J0NES_3 

This command interrupts the image running in process JONES_3 and brings 
the process under debugger control. Process JONES_3 must be in the same 
VMS job as the process in which the debugger was invoked. Also, the image 
must not have been linked with the /NOTRACEBACK qualifier. 
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Ctrl/C 

When entered from within a debugging session, aborts the execution °f a 
debugger command or interrupts program execution without interrupting the 
debugging session. 

__ Note--- 

Do not use Ctrl/Y from within a debugging session. 


Format 

[ctfiTcl 

Description 

Pressing Ctrl/C enables you to abort the execution of a debugger command or to 
interrupt program execution without interrupting the debugging session. This is 
useful when, for example, the program is executing an infinite loop that does not 
have a breakpoint, or you want to abort a debugger command that takes a long 
time to complete. The debugger prompt is then displayed, so that you can enter 
debugger commands. 

After a Ctrl/C interruption, any processes of a multiprocess program that were 
executing images are in the "interrupted” state. 

If your program already has a Ctrl/C AST service routine enabled, use the SET 
ABORT_KEY command to assign the debugger’s abort function to another Ctrl- 
key sequence. Note, however, that many Ctrl-key sequences have VMS predefined 
functions, and the SET ABORT.KEY command enables you to override such 
definitions (see the VMS DCL Concepts Manual). Some of the Ctrl-key characters 
not used by the VMS operating system are G, K, N, and P. 

If your program does not have a Ctrl/C AST service routine enabled, and you 
assign the debugger’s abort function to another Ctrl-key sequence, the Ctrl/C 
sequence then behaves like Ctrl/Y—that is, it interrupts the debugging session 
and returns you to DCL level. 

Do not use Ctrl/Y from within a debugging session. Always use either Ctrl/C 
or an equivalent Ctrl-key sequence established with the SET ABORTJKEY 
command. 

You can use the SPAWN and ATTACH commands to leave and return to a 
debugging session without losing the debugging context. 

Related commands: 

ATTACH 

Ctrl/Y 

(SET,SHOW) ABORT_KEY 
SPAWN 
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Example 

DBG> GO 


| Ctrl/Cj 

DBG^EXAMINE/BYTE 1000:101000 Ishould have typed 1000:1010 

1004: 0 
1008: 0 
1012: 0 
1016: 0 


| Ctrl/Cl 

%DEBUG-W-ABORTED, command aborted by user request 


This example shows how to use the Ctrl/C sequence to, first, interrupt program 
execution, and then, abort the execution of a debugger command. 


CD-39 









Debugger Command Dictionary 
Ctrl/W, Ctrl/Z 


Ctrl/W, Ctrl/Z 


Ctrl/W refreshes the screen in screen mode (like DISPLAY/REFRESH). 
Ctrl/Z ends a debugging session (like EXIT). 


Format 

I Ctrl/W | 

[Ctri/Z] 


Description 

For an explanation of the Ctrl/W and Ctrl/Z commands, see the descriptions of 
the DISPLAY/REFRESH and EXIT commands, respectively. 
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Ctrl/Y 


When entered from DCL level, interrupts an image that is running without 
debugger control, enabling you to then invoke the debugger with the DCL 
DEBUG command. 

-—- Note ____ 

Do not use Ctrl/Y from within a debugging session. Instead, use Ctrl/C or 
an equivalent abort-key sequence established with the SET ABORT.KEY 
command. 


Format 

[CWY] 


Description 

Pressing Ctrl/Y at the DCL level enables you to interrupt an image that is 
running without debugger control, so that you can then invoke the debugger with 
the DCL command DEBUG. 

You can bring an image under debugger control only if, as a minimum , that image 
was linked with the /TRACEBACK qualifier (/TRACEBACK is a LINK command 
default). Also, you can reference all of the image’s symbols while debugging only 
if its modules were compiled and linked with the /DEBUG qualifier (in that case 
you could use the DCL command RUN/NODEBUG to execute the image without 
the debugger). 

When you press Ctrl/Y to interrupt the image’s execution, control is passed to 
the DCL command interpreter. If you then type the DCL command DEBUG, the 
interrupted image is brought under control of the debugger. The debugger sets its 
language dependent parameters to the source language of the module in which 
execution was interrupted and displays its prompt. You can then determine 
where execution was suspended by entering a SHOW CALLS command (and a 
SHOW PROCESS command, in the case of a multiprocess program). 

When a new debugging session is started, a process is created to run the main 
debugger image (DEBUGSHR.EXE) that controls the session. The main debugger 
process is a subprocess of the process that is running the image to be debugged. 
The debugger displays its banner when a new session is started. 

Other details about the effect of a Ctrl/Y-DEBUG sequence depend on the 
debugging configuration (default or multiprocess), which is determined by the 
current definition of the logical name DBG$PROCESS in the process where the 
interrupted image was executing. 

Default Debugging Configuration 

The default debugging configuration is achieved when DBG$PROCESS is either 
undefined or has the value DEFAULT. In this case a new default debugging 
session is started every time you invoke the debugger with the Ctrl/Y-DEBUG 
sequence (see Example 1). 
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Multiprocess Debugging Configuration 

The multiprocess debugging configuration is achieved when DBG$PROCESS has 
the job definition MULTIPROCESS. In this case, the effect of a Ctrl/Y—DEBUG 
sequence is as follows: 

• If a multiprocess debugging session does not already exist in the same job 
as the process running the interrupted image, a new multiprocess debugging 
session is created (see Example 2). 

• If a multiprocess debugging session already exists in the same job, the 
interrupted image and its process come under control of that session. In this 
case the debugger does not display its banner. 

Within a debugging session, you can use the CONNECT command to connect an 
image that is running without debugger control in another process (of the same 
job) to that debugging session. 

Related commands: 

CONNECT 

Ctrl/C 

$ DEBUG (at DCL level) 

Examples 

1. $ RUN/NODEBUG TEST_B 


[CtiWl 

Interrupt 
$ DEBUG 

VAX DEBUG Version 5.5 

IDEBUG-I-INITIAL, language is ADA, module set to SWAP 
DBG> 

The RUN/NODEBUG command executes the image TEST_B without 
debugger control. Execution is interrupted with Ctrl/Y. The DEBUG command 
then causes the debugger to be invoked. The debugger displays its banner, 
sets the language-dependent parameters to the language (Ada, in this case) 
of the module (SWAP) in which execution was interrupted, and displays the 
prompt. This is the default debugging configuration, as indicated by the 
DBG> prompt. 

2. $ DEFINE/JOB DBG$PROCESS MULTIPROCESS 

$ RUN/NODEBUG PR0G2 


[CtiWl 

Interrupt 
$ DEBUG 

VAX DEBUG Version 5.5 


%DEBUG-I-INITIAL, language is FORTRAN, module set to SUB4 
predefined trace on activation at SUB4\%LINE 12 in %PROCESS_NUMBER 


DBG 1> 


1 
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The DEFINE/JOB command establishes a multiprocess debugging 
configuration. The RUN/NODEBUG command executes the image PROG2 
without debugger control. The Ctrl/Y—DEBUG sequence interrupts execution 
and invokes the debugger. The VAX DEBUG banner indicates that a new 
debugging session has been started. The process-specific prompt (DBG_1>) 
indicates that this is a multiprocess configuration and that execution is 
suspended in process 1, which is running PROG2. The activation tracepoint 
indicates where execution was interrupted when the debugger took control of 
the process. 
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DECLARE 

Declares a formal parameter within a command procedure. This enables you 
to pass an actual parameter to the procedure when entering an @ (Execute 
Procedure) command. 


Format 


DECLARE p-name:p-kind [,p-name:p-kind[, . .. ]] 


Parameters 

p-name 

Specifies a formal parameter (a symbol) that is declared within the command 
procedure. 

Do not specify a null parameter (represented either by two consecutive commas 
or by a comma at the end of the command). 


p-kind 

Specifies the parameter kind of a formal parameter. Valid keywords are as 
follows: 


ADDRESS 

COMMAND 

VALUE 


Specifies that the actual parameter is interpreted as an address 
expression. Has the same effect as the command DEFINE 
/ADDRESS p-name = actual-parameter . 

Specifies that the actual parameter is interpreted as a command. 
Has the same effect as the command DEFINE/COMMAND 
p-name = actual-parameter. 

Specifies that the actual parameter is interpreted as a value 
expression in the current language. Has the same effect as the 
command DEFINE/VALUE p-name = actual-parameter . 


Description 

The DECLARE command is valid only within a command procedure. 

The DECLARE command binds one or more actual parameters, specified on 
the command line following the @ (Execute Procedure) command, to formal 
parameters (symbols) declared within a command procedure. 

Each p-name:p-kind pair specified by a DECLARE command binds one formal 
parameter to one actual parameter. Formal parameters are bound to actual 
parameters in the order in which the debugger processes the parameter 
declarations. If you specify several formal parameters on a single DECLARE 
command, the leftmost formal parameter is bound to the first actual parameter, 
the next formal parameter is bound to the second, and so on. If you use a 
DECLARE command in a loop, the formal parameter is bound to the first actual 
parameter on the first iteration of the loop; the same formal parameter is bound 
to the second actual parameter on the next iteration, and so on. 

Each parameter declaration acts like a DEFINE command: it associates a formal 
parameter with an address expression, a command, or a value expression in 
the current language, according to the parameter kind specified. The formal 
parameters themselves are consistent with those accepted by the DEFINE 
command and can in fact be deleted from the symbol table with the DELETE 
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command. For more information, see the descriptions of the DEFINE and 
DELETE commands. 

The %PARCNT built-in symbol, which can be used only within a command 
procedure, enables you to pass a variable number of parameters to a command 
procedure. The value of %PARCNT is the number of actual parameters passed to 
the command procedure. 

Related commands: 


@ (Execute Procedure) 

DEFINE 

DELETE 


Examples 


1 . ! ***** Command Procedure EXAM.COM ***** 

SET OUTPUT VERIFY 
DECLARE K:ADDRESS 
EXAMINE K 

DBG> 0EXAM ARR4 

%DEBUG-I-VERIFYIC, entering command procedure EXAM 
DECLARE K:ADDRESS 
EXAMINE K 
PROG_8\ARR4 

(1): 18 


( 2 ): 

(3) : 

(4) : 


1 

0 

1 


IDEBUG-I-VERIFYIC, exiting command procedure EXAM 
DBG> 

In this example, the DECLARE K:ADDRESS command declares the formal 
parameter K within command procedure EXAM.COM. When EXAM.COM 
is executed, the actual parameter passed to EXAM.COM is interpreted as 
an address expression, and the EXAMINE K command displays the value of 
that address expression. The SET OUTPUT VERIFY command causes the 
commands to echo when they are read by the debugger. 

At the debugger prompt, the @EXAM ARR4 command executes EXAM.COM, 
passing the actual parameter ARR4. Within EXAM.COM, ARR4 is 
interpreted as an address expression (an array variable, in this case). 

2. i ***** Debugger Command Procedure EXAM__GO.COM ***** 

DECLARE L:ADDRESS, M:COMMAND 
EXAMINE L; M 

DBG> @EXAM_GO X "@DUMP" 

In this example, the command procedure EXAM_GO.COM accepts two 
parameters, an address expression (L) and a command string (M). The 
address expression is then examined and the command is executed. 

At the debugger prompt, the @EXAM_GO X "@DUMP" command executes 
EXAM_GO.COM, passing the address expression X and the command string 
@DUMP. 
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3. j ***** Debugger Command Procedure VAR.DBG ***** 

SET OUTPUT VERIFY 

FOR I - 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X) 

DBG> @VAR.DBG 12,37,45 

%DEBUG-I-VERIFYIC, entering command procedure VAR.DBG 
FOR I * 1 TO IPARCNT DO (DECLARE X:VALUE; EVALUATE X) 

12 

37 

45 

IDEBUG-I-VERIFYIC, exiting command procedure VAR.DBG 
DBG> 

In this example, the command procedure VAR.DBG accepts a variable number 
of parameters. That number is stored in the built-in symbol %PARCNT. 

At the debugger prompt, the ©VAR.DBG command executes VAR.DBG, 
passing the actual parameters 12, 37, and 45. Therefore, %PARCNT has the 
value 3, and the FOR loop is repeated 3 times. The FOR loop causes the 
DECLARE command to bind each of the three actual parameters (starting 
with 12) to a new declaration of X. Each actual parameter is interpreted as 
a value expression in the current language, and the EVALUATE X command 
displays that value. 
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DEFINE 


Assigns a symbolic name to an address expression, command, or value. 


Format 

DEFINE symbol-name=parameter [,symbol-name=parameter[, ... ]] 

Parameters 

symbol-name 

Specifies a symbolic name to be assigned to an address, command, or value. The 
symbolic name can be composed of alphanumeric characters and underscores. 

The debugger converts lowercase alphabetic characters to uppercase. The first 
character must not be a number. The symbolic name must be no more than 31 
characters long. 

parameter 

Depends on the qualifier specified. 

Qualifiers 

/ADDRESS 

Specifies that the defined symbol is an abbreviation for an address expression. In 
this case, parameter is an address expression. DEFINE/ADDRESS is the default. 

/COMMAND 

Specifies that the defined symbol is treated as a new debugger command. In 
this case, parameter is a quoted character string. This qualifier provides, in 
simple cases, essentially the same capability as the DCL command "symbol := 
string ." To define complex commands, you might need to use command procedures 
with formal parameters. For more information about declaring parameters to 
command procedures, see the description of the DECLARE command. 

/LOCAL 

Specifies that the definition remain local to the command procedure in which the 
DEFINE command is issued. The defined symbol is not visible at the debugger 
command level. By default, a symbol defined within a command procedure is 
visible outside that procedure. 

/VALUE 

Specifies that the defined symbol is an abbreviation for a value. In this case, 
parameter is a language expression in the current language. 

Description 

The DEFINE/ADDRESS command enables you to assign a symbolic name to 
an address expression in your program. For example, you can define a symbol 
for a nonsymbolic program location or for a symbolic program location having a 
long pathname prefix. Then, you can refer to that program location by the newly 
defined symbol. The /ADDRESS qualifier is the default definition qualifier. 

The DEFINE/COMMAND command enables you to define abbreviations for 
debugger commands or even define new commands, either from the debugger 
command level or from command procedures. 
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The DEFINE/VALUE command enables you to assign a symbolic name to a value 
(or the result of evaluating a language expression). 

Use the /LOCAL qualifier to confine symbol definitions to command procedures. 
By default, defined symbols are global (visible outside the command procedure). 

If you plan to enter several DEFINE commands with the same qualifier, you 
can first use the SET DEFINE command to establish a new default qualifier 
(for example, SET DEFINE COMMAND makes the DEFINE command behave 
like DEFINE/COMMAND). Then you do not have to use that qualifier with 
the DEFINE command. You can override the current default qualifier for the 
duration of a single DEFINE command by specifying another qualifier. 

In symbol translation, the debugger searches symbols you define during the 
debugging session first. So if you define a symbol that already exists in your 
program, the debugger translates the symbol according to its defined definition, 
unless you specify a pathname prefix. 

If a symbol is redefined, the previous definition is canceled, even if different 
qualifiers were used with the DEFINE command. 

Definitions created with the DEFINE/ADDRESS and DEFINE/VALUE commands 
are available only when the image in whose context they were created is the 
current image. If you use the SET IMAGE command to establish a new current 
image, these definitions are temporarily unavailable. Definitions created with the 
DEFINE/COMMAND and DEFINE/KEY commands are always available for all 
images, however. 

Use the SHOW SYMBOL/DEFINED command to determine the equivalence 
value of a symbol. 

Use the DELETE command to cancel a symbol definition. 

Related commands: 

DECLARE 

DELETE 

SET IMAGE 

SHOW DEFINE 

SHOW SYMBOL/DEFINED 

Examples 

1. DBG> DEFINE CHK=MAIN\LOOP+10 

This command assigns the symbol CHK to the address MAIN\LOOP+10. 

2. DBG> DEFINE/VALUE COUNTERS 

DBG> SET TRACE/SILENT R DO (DEFINE/VALUE COUNTER = COUNTER+1) 

In this example, the first command assigns a value of 0 to the symbol 
COUNTER. The second command causes the debugger to increment the value 
of the symbol COUNTER by 1 whenever address R is encountered. In other 
words, this example counts the number of calls to R. 

3. DBG> DEFINE/COMMAND BRE = "SET BREAK" 

This command assigns the symbol BRE to the debugger command SET 
BREAK. 
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DEFINE/KEY 

Assigns a string to a function key. 

Format 

DEFINE/KEY key-name "equiv-string" 


Parameters 

key-name 

Specifies a function key to be assigned a string. Valid key names are as follows: 


Key Name 

LK201 Keyboard 

VT100-Type 

VT52-Type 

PF1 

PF1 

PF1 

Blue 

PF2 

PF2 

PF2 

Red 

PF3 

PF3 

PF3 

Black 

PF4 

PF4 

PF4 


KP0-KP9 

Keypad 0-9 

Keypad 0-9 

Keypad 0-9 

PERIOD 

Keypad period (.) 

Keypad period (.) 


COMMA 

Keypad comma (,) 

Keypad comma (,) 


MINUS 

Keypad minus (-) 

Keypad minus (-) 


ENTER 

ENTER 

ENTER 

ENTER 

El 

Find 



E2 

Insert Here 



E3 

Remove 



E4 

Select 



E5 

Prev Screen 



E6 

Next Screen 



HELP 

Help 



DO 

Do 



F6-F20 

F6-F20 




On LK201 keyboards: 

• You cannot define keys FI to F5 or the arrow keys (E7 to E10). 

• You can define keys F6 to F14 only if you have first entered the DCL 
command SET TERMINAL/NOLINE_EDITING. In that case, the line-editing 
functions of the LEFT and RIGHT arrow keys (E8 and E9) are disabled. 

equiv-string 

Specifies the string to be processed when the specified key is pressed. Typically, 
this is one or more debugger commands. If the string includes any space or 
nonalphanumeric characters (for example, a semicolon separating two commands) 
enclose the string in quotation marks ("). 
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Qualifiers 

/ECHO (default) 

/NOECHO 

Controls whether the command line is displayed after the key has been pressed. 
Do not use /NOECHO with /NOTERMINATE. 

/IF_STATE=(state-name[, ... ]) 

/NOIF_STATE (default) 

Specifies one or more states to which a key definition applies. The /IF_STATE 
qualifier assigns the key definition to the specified states. You can specify 
predefined states, such as DEFAULT and GOLD, or user-defined states. A state 
name can be any appropriate alphanumeric string. The /NOIF_STATE qualifier 
assigns the key definition to the current state. 

/LOCK_STATE 
/NOLOCK_STATE (default) 

Controls how long the state set by /SET_STATE remains in effect after the 
specified key is pressed. The /LOCK_STATE qualifier causes the state to remain 
in effect until it is changed explicitly (for example, with a SET KEY/STATE 
command). The /NOLOCK_STATE qualifier causes the state to remain in effect 
only until the next terminator character is typed, or until the next defined 
function key is pressed. 

/LOG (default) 

/NOLOG 

Controls whether a message is displayed indicating that the key definition has 
been successfully created. The /LOG qualifier displays the message. 

/SET_STATE=state-name 
/NOSET_STATE (default) 

Controls whether pressing the key changes the current key state. The /SET_ 
STATE qualifier causes the current state to change to the specified state when 
you press the key. The /NOSET_STATE qualifier causes the current state to 
remain in effect. 

/TERMINATE 
/NOTERMINATE (default) 

Controls whether the specified string is terminated (processed) when the key is 
pressed. The /TERMINATE qualifier causes the string to be terminated when the 
key is pressed. The /NOTERMINATE qualifier enables you to press other keys 
before terminating the string by pressing the Return key. 

Description 

Keypad mode must be enabled (SET MODE KEYPAD) before you can use this 
command. Keypad mode is enabled by default. 

The DEFINE/KEY command enables you to assign a string to a function key, 
overriding any predefined function that was bound to that key (the predefined 
key functions are listed in Appendix B). When you then press the key, the 
debugger enters the currently associated string into your command line. The 
DEFINE/KEY command is like the DCL DEFINE/KEY command. 
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On VT52- and VTlOO-series terminals, the function keys you can use include all 
of the numeric keypad keys. Newer terminals and workstations have the LK201 
keyboard. On LK201 keyboards, the function keys you can use include all of the 
numeric keypad keys, the nonarrow keys of the editing keypad (Find, Insert Here, 
and so on), and keys F6 to F20 at the top of the keyboard. 

A key definition remains in effect until you redefine the key, enter the DELETE 
/KEY command for that key, or exit the debugger. You can include key definitions 
in a command procedure, such as your debugger initialization file. 

The /IF_STATE qualifier enables you to increase the number of key definitions 
available on your terminal. The same key can be assigned any number of 
definitions as long as each definition is associated with a different state. 

By default, the current key state is the "DEFAULT" state. The current state can 
be changed with the SET KEY/STATE command, or by pressing a key that causes 
a state change (a key that was defined with the DEFINE/KEY/LOCK_STATE 
/STATE qualifier combination). 

Related commands: 

DELETE/KEY 
(SET,SHOW) KEY 


Examples 

1. DBG> SET KEY/STATE=GOLD 

% DEBUG-1-SETKEY, keypad state has been set to GOLD 
DBG> DEFINE/KEY/TERMINATE KP9 "SET RADIX/OVERRIDE HEX" 

IDEBUG-I-DEFKEY, GOLD key KP9 has been defined 
DBG> 

In this example, the SET KEY command establishes GOLD as the current 
key state. The DEFINE/KEY command assigns the SET RADIX/OVERRIDE 
HEX command to keypad key 9 for the current state (GOLD). The command 
is processed when the key is pressed. 

2. DBG> DEFINE/KEY/IF_STATE=BLUE KP9 "SET BREAK ILINE " 

%DEBUG-I-DEFKEY, BLUE key KP9 has been defined 

DBG> 

This command assigns the unterminated command string "SET BREAK 
%LINE" to keypad key 9 for the BLUE state. After pressing the keypad key 
sequence BLUE-KP9, you can enter a line number and then press the Return 
key to terminate and process the SET BREAK command. 

3. DBG> SET KEY/STATE=DEFAULT 

%DEBUG-I-SETKEY, keypad state has been set to DEFAULT 
DBG> DEFINE/KEY/SET_STATE=RED/LOCK_STATE F12 "" 

%DEBUG-I-DEFKEY, DEFAULT key F12 has been defined 
DBG> 

In this example, the SET KEY command establishes DEFAULT as the current 
state. The DEFINE/KEY command makes key F12 (LK201 keyboard) a state 
key. Pressing F12 while in the DEFAULT state causes the current state to 
become RED. The key definition is not terminated and has no other effect 
(a null string is assigned to F12). After pressing F12, you can enter "RED" 
commands by pressing keys that have definitions associated with the RED 
state. 
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DEFINE/PROCESS_GROUP 

Assigns a symbolic name to a list of process specifications. 

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 

Format 

DEFINE/PROCESS_GROUP process-group-name =process-spec[, ... ] 

Parameters 

process-group-name 

Specifies a symbolic name to be assigned to a list of process specifications. The 
symbolic name can be composed of alphanumeric characters and underscores. 
The debugger converts lowercase alphabetic characters to uppercase. The first 
character must not be a number. The symbolic name must be no more than 31 
characters long. 


process-spec 

Specifies a process. Use any of the following forms: 


[%PROCESS_NAME] process-name 

[%PROCESS_NAME] " process-name ' 

%PROCESS_PID processjd 

%PROCESS_NUMBER proc-number 
(or %PROC proc-number ) 

process-group-name 

%NEXT_PROCESS 

%PREVIOUS_PROCESS 

%VISIBLE_PROCESS 


The VMS process name, if that 
name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 

The VMS process name, if that name 
contains space or lowercase characters. 
You can also use apostrophes (') instead 
of quotation marks (" ). 

The VMS process identification number 
(PID, a hexadecimal number). 

The number assigned to a process 
when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. Do not 
specify a recursive symbol definition. 

The process after the visible process in 
the debugger’s circular process list. 

The process previous to the visible 
process in the debugger’s circular 
process list. 

The process whose call stack, register 
set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 

name is created but contains no 


If you do not specify a process, the symbolic 
process entries. 
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Description 

The DEFINE/PROCESS_GROUP command assigns a symbol to list of process 
specifications. You can then use the symbol in any command where a list of 
process specifications is allowed. 

The DEFINE/PROCESS_GROUP command does not verify the existence of a 
specified process. This enables you to specify processes that do not yet exist. 

To identify a symbol that was defined with the DEFINE/PROCESS_GROUP 
command, use the SHOW SYMBOL/DEFINED command. To delete a symbol that 
was defined with the DEFINE/PROCESS_GROUP command, use the DELETE 
command. 

Related commands: 

DELETE 

(SET,SHOW) DEFINE 
SHOW SYMBOL/DEFINED 

Examples 

1. DBG_1> DEFINE/PROCESS_GROUP SERVERS=FILE_SERVER,NET_SERVER 
DBG_1> SHOW PROCESS SERVERS 

Number Name Hold State Current PC 

* 1 FILE_SERVER step FS_PROG\%LINE 37 

2 NETWORK_SERVER break NET PROG\%LINE 24 

DBG_1> 

This DEFINE/PROCESS_GROUP command assigns the symbolic name 
SERVERS to the process group consisting of FILE_SERVER and NETWORK. 
SERVER. The SHOW PROCESS SERVERS command displays information 
about the processes that make up the group SERVERS. 

2. USER_3> DEFINE/PROCESS_GROUP G1=%PR0CESS_NUMBER INVISIBLE PROCESS 
USER_3> SHOW SYMBOL/DEFINED G1 

defined G1 

bound to: "%PROCESS_NUMBER 1, %VISIBLE_PROCESS" 
was defined /process_group 
USER_3> DELETE G1 

This DEFINE/PROCESS.GROUP command assigns the symbolic name G1 to 
the process group consisting of process 1 and the visible process (process 3). 
The SHOW SYMBOL/DEFINED G1 command identifies the defined symbol 
Gl. The DELETE G1 command deletes the symbol from the DEFINE symbol 
table. 

3. DBG_2> DEFINE/PROCESS_GROUP A = B,C,D 
DBG_2> DEFINE/PROCESS_GROUP B = E,F,G 
DBG_2> DEFINE/PROCESS_GROUP E = I,J,A 

IDEBUG-E-NORECSYM, recursive PROCESS_GROUP symbol definition 
encountered at or near "A" 

DBG_2> 

This series of DEFINE/PROCESS_GROUP commands illustrate valid and 
invalid uses of the command. 
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DELETE 


Deletes a symbol definition that was established with the DEFINE command. 


Format 

DELETE [symbol-name[, ... ]] 

Parameters 

symbol-name 

Specifies a symbol whose definition is to be deleted from the DEFINE symbol 
table. Do not use the asterisk (*) wildcard character. Instead, use the /ALL 
qualifier. Do not specify a symbol name with /ALL. If you use the /LOCAL 
qualifier, the symbol specified must have been previously defined with the 
DEFINE/LOCAL command. If you do not specify /LOCAL, the symbol specified 
must have been previously defined with the DEFINE command without /LOCAL. 

Qualifiers 

/ALL 

Deletes all global DEFINE definitions. If you also specify /LOCAL, deletes all 
local DEFINE definitions associated with the current command procedure (but 
not the global DEFINE definitions). Do not specify a symbol name with /ALL. 

/LOCAL 

Deletes the (local) definition of the specified symbol from the current command 
procedure. The symbol must have been previously defined with the DEFINE 
/LOCAL command. 

Description 

The DELETE command deletes either a global DEFINE symbol or a local 
DEFINE symbol. A global DEFINE symbol is a symbol defined with the DEFINE 
command without the /LOCAL qualifier. A local DEFINE symbol is a symbol 
defined in a debugger command procedure with the DEFINE/LOCAL command, 
so that its definition is confined to that command procedure. 

Related commands: 

DECLARE 

DEFINE 

SHOW DEFINE 

SHOW SYMBOL/DEFINED 

Examples 

1 DBG> DEFINE X = INARR, Y = OUTARR 
DBG> DELETE X,Y 

In this example, the DEFINE command defines X and Y as global symbols 
corresponding to INARR and OUTARR, respectively. The DELETE command 
deletes these two symbol definitions from the global symbol table. 
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DBG> DELETE/ALL/LOCAL 

In this example, the DELETE/ALL/LOCAL commmand deletes all local 
symbol definitions from the current command procedure. 
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DELETE/KEY 

Deletes a key definition that was established with the DEFINE/KEY command or, 
by default, by the debugger. 


Format 

DELETE/KEY [key-name] 


Parameters 

key-name 

Specifies a key whose definition is to be deleted. Do not use the asterisk (*) 
wildcard character. Instead, use the /ALL qualifier. Do not specify a key name 
with /ALL. Valid key names are as follows: 


Key Name 

LK201 Keyboard 

VT100-Type 

VT52-Type 

PF1 

PF1 

PF1 

Blue 

PF2 

PF2 

PF2 

Red 

PF3 

PF3 

PF3 

Black 

PF4 

PF4 

PF4 


KP0-KP9 

Keypad 0-9 

Keypad 0-9 

Keypad 0-9 

PERIOD 

Keypad period (.) 

Keypad period (.) 


COMMA 

Keypad comma (,) 

Keypad comma (,) 


MINUS 

Keypad minus (-) 

Keypad minus (-) 


ENTER 

ENTER 

ENTER 

ENTER 

El 

Find 



E2 

Insert Here 



E3 

Remove 



E4 

Select 



E5 

Prev Screen 



E6 

Next Screen 



HELP 

Help 



DO 

Do 



F6-F20 

F6-F20 




Qualifiers 


/ALL 

Deletes all key definitions in the specified state. Do not specify a key name with 
/ ATI. If you do not specify a state, all key definitions in the current state are 
deleted. Use the /STATE qualifier to specify one or more states. 

/LOG (default) 

/NOLOG 

Controls whether a message is displayed indicating that the specified key 
definitions have been deleted. The /LOG qualifier displays the message. 
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/STATE=(state-name [,...]) 

/NOSTATE (default) 

Selects one or more states for which a key definition is to be deleted. The /STATE 
qualifier deletes key definitions for the specified states. You can specify predefined 
key states, such as DEFAULT and GOLD, or user-defined states. A state name 
can be any appropriate alphanumeric string. The /NOSTATE qualifier deletes the 
key definition for the current state only. 

By default, the current key state is the "DEFAULT" state. The current state can 
be changed with the SET KEY/STATE command, or by pressing a key that causes 
a state change (a key that was defined with the DEFINE/KEY/LOCK_STATE 
/STATE qualifier combination). 

Description 

The DELETE/KEY command is like the DCL command DELETE/KEY. 

Keypad mode must be enabled (SET MODE KEYPAD) before you can use this 
command. Keypad mode is enabled by default. 

Related commands: 

DEFINE/KEY 
(SET,SHOW) KEY 

Examples 

1. DBG> DELETE/KEY KP4 

% DEBUG-1-DELKEY, DEFAULT key KP4 has been deleted 
DBG> 

This command deletes the key definition for keypad key KP4 in the state last 
set by the SET KEY command (by default, this is the DEFAULT state). 

2. DBG> DELETE/KEY/STATE=(BLUE,RED) COMMA 

IDEBUG-I-DELKEY, BLUE key COMMA has been deleted 
IDEBUG-I-DELKEY, RED key COMMA has been deleted 
DBG> 

This command deletes the key definition for keypad key COMMA in the 
BLUE and RED states. 
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DEPOSIT 

Changes the value of a program variable. More generally, deposits a new value at 
the location denoted by an address expression. 

Format 

DEPOSIT address-expression = language-expression 

Parameters 

address-expression 

Specifies the location into which the value of the language expression is to be 
deposited. With high-level languages, this is typically the name of a variable 
and can include a pathname to specify the variable uniquely. More generally, 
an address expression can also be a memory address or a register and can be 
composed of numbers (offsets) and symbols, as well as one or more operators, 
operands, or delimiters. Appendix D identifies the debugger’s built-in symbols 
for the VAX registers and identifies the operators that can be used in address 
expressions. 

You cannot specify an entire aggregate variable (a composite data structure such 
as an array or a record). To specify an individual array element or a record 
component, use the syntax of the current language. 

See Chapter 11 for information that is specific to vector registers and vector 
instructions. 

language-expression 

Specifies the value to be deposited. You can specify any language expression that 
is valid in the current language. For most languages, the expression can include 
the names of simple (noncomposite, single-valued) variables but not the names 
of aggregate variables (such as arrays or records). If the expression contains 
symbols with different compiler generated types, the debugger uses the rules of 
the current language to evaluate the expression. 

If the expression is an ASCII string or a VAX assembly-language instruction, you 
must enclose it in quotation marks (" ) or apostrophes ('). If the string contains 
quotation marks or apostrophes, use the other delimiter to enclose the string. 

If the string has more characters (1-byte ASCII) than can fit into the program 
location denoted by the address expression, the debugger truncates the extra 
characters from the right. If the string has fewer characters, the debugger pads 
the remaining characters to the right of the string by inserting ASCII space 
characters. 


Qualifiers 


/ascic 

Deposits a counted ASCII string into the specified location. You must specify a 
string on the right-hand side of the equal sign. The deposited string is preceded 
by a 1-byte count field that gives the length of the string. /AC is also accepted. 
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/ASCID 

Deposits an ASCII string into the address given by a string descriptor that is 
at the specified location. You must specify a string on the right-hand side of the 
equal sign. The specified location must contain a string descriptor. If the string 
lengths do not match, the string is either truncated on the ri gh t or padded with 
space characters on the right. /AD is also accepted. 

/ASCII :n 

Deposits n bytes of an ASCII string into the specified location. You must specify 
a string on the right-hand side of the equal sign. If its length is not n, the string 
is truncated or padded with space characters on the right. If n is omitted, the 
actual length of the data item at the specified location is used. 

/ASCIW 

Deposits a counted ASCII string into the specified location. You must specify a 
string on the right-hand side of the equal sign. The deposited string is preceded 
by a 2-byte count field that gives the length of the string. /AW is also accepted. 

/ASCIZ 

Deposits a zero-terminated ASCII string into the specified location. You must 
specify a string on the right-hand side of the equal sign. The deposited string 
is terminated by a zero byte that indicates the end of the string. /AZ is also 
accepted. 

/BYTE 

Deposits a 1-byte integer into the specified location. 

/D_FLOAT 

Converts the expression on the right-hand side of the equal sign to the D_floating 
type (length 8 bytes) and deposits the result into the specified location. Values 
of type D_floating can range from .29 * 1CT 38 to 1.7 * 10 38 with approximately 16 
decimal digits precision. 

/DATE_TIME 

Converts a string representing a date and time (for example, 21-DEC-1988 
21:08:47.15) to the VMS internal format for date and time and deposits that 
value (length 8 bytes) into the specified location. Specify an absolute date and 
time in the following format: [ dd-mmm-y yyy [:]] [hh:mm:ss.cc]. 

/FLOAT 

Converts the expression on the right-hand side of the equal sign to the F_floating 
type (length 4 bytes) and deposits the result into the specified location. Values 
of type F_floating can range from .29 * 10~ 38 to 1.7 * 10 38 with approximately 7 
decimal digits precision. 

/G_FLOAT 

Converts the expression on the right-hand side of the equal sign to the G_floating 
type (length 8 bytes) and deposits the result into the specified location. Values of 
type G_floating can range from .56 * 10~ 308 to .9 * 10 308 with approximately 15 
decimal digits precision. 

/H_FLOAT 

Converts the expression on the right-hand side of the equal sign to the H_floating 
type (length 16 bytes) and deposits the result into the specified location. Values 
of type H_floating can range from .84 * 1CT 4932 to .59 * 10 4932 with approximately 
33 decimal digits precision. 
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/INSTRUCTION 

Deposits a VAX assembly-language instruction into the specified location. The 
expression on the right-hand side of the equal sign must be a string representing 
a VAX instruction. 

/LONGWORD 

Deposits a longword integer (length 4 bytes) into the specified location. 

/OCTAWORD 

Deposits an octaword integer (length 16 bytes) into the specified location. 

/PACKED:n 

Converts the expression on the right-hand side of the equal sign to a packed 
decimal representation and deposits the resulting value into the specified 
location. The value of n is the number of decimal digits. Each digit occupies one 
nibble (4 bits). 

/QUADWORD 

Deposits a quadword integer (length 8 bytes) into the specified location. 

/TASK 

Applies to tasking (multithread) programs. 

Deposits a task value (a task name or a task ID such as %TASK 3) into the 
specified location. The deposited value must be a valid task value. 

/TYPE=(name) 

Converts the expression to be deposited to the type denoted by name (which must 
be the name of a variable or data type declared in the program), then deposits 
the resulting value into the specified location. This enables you to specify a 
user-declared type. 

You must use parentheses around the type expression. 

/WORD 

Deposits a word integer (length 2 bytes) into the specified location. 


Description 

The DEPOSIT command can be used to change the contents of any memory 
location or register that is accessible in your program. For high-level languages 
the command is used mostly to change the value of a variable (an integer, real, 
string, array, record, and so on). 

The DEPOSIT command is like an assignment statement in most programming 
languages. The value of the expression specified to the right of the equal sign is 
assigned to the variable or other location specified to the left of the equal sign. 
For Ada and Pascal, you can use instead of "=" in the command syntax. 

The debugger recognizes the compiler-generated types associated with symbolic 
address expressions (symbolic names declared in your program). Symbolic 
address expressions include the following entities: 

• Variable names. When specifying a variable with the DEPOSIT command, 
use the same syntax that is used in the source code. 
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• Routine names, labels, and line numbers. These are associated with VAX 
instructions. You can deposit instructions using basically the same techniques 
as when depositing into string variables. However, you must also use the 
/INSTRUCTION qualifier or first enter a SET TYPE INSTRUCTION or SET 
TYPE/OVERRIDE INSTRUCTION command. 

In general, when you enter a DEPOSIT command, the debugger takes the 
following action: 

• It evaluates the address expression specified to the left of the equal sign, to 
yield a program location. 

• If the program location has a symbolic name, the debugger associates the 
location with the symbol’s compiler generated type. If the location does not 
have a symbolic name (and, therefore, no associated compiler generated 
type) the debugger associates the location with the type longword integer by 
default. This means that, by default, you can deposit integer values that do 
not exceed 4 bytes into these locations. 

See Chapter 11 for information that is specific to vector registers and vector 
instructions. 

• It evaluates the language expression specified to the right of the equal si gn , 
in the syntax of the current language and in the current radix, to yield a 
value. The current language is the language last established with the SET 
LANGUAGE command. If no SET LANGUAGE command was entered, the 
current language is, by default, the language of the module containing the 
main program. 

• It checks that the value and type of the language expression is consistent 
with the type of the address expression. If you try to deposit a value that 
is incompatible with the type of the address expression, the debugger issues 
a diagnostic message. If the value is compatible, the debugger deposits the 
value into the location denoted by the address expression. 

The debugger might do type conversion during a deposit operation if the language 
rules allow it. For example a real value that is specified to the right of the equal 
sign might be converted to an integer value if it is being deposited into a location 
with an integer type. In general, the debugger tries to follow the assignment 
rules for the current language. 

There are several ways of changing the type associated with a program location 
so that you can deposit data of a different type into that location: 

• To change the default type for all locations that do not have a symbolic name, 
you can specify a new type with the SET TYPE command. 

• To change the default type for all locations (both those that do and do not 
have a symbolic name), you can specify a new type with the SET TYPE 
/OVERRIDE command. 

• To override the type currently associated with a particular location for the 
duration of a single DEPOSIT command, you can specify a new type by means 
of a qualifier (/ASCILrc, /BYTE, /TYPE =(name), and so on). 

The debugger can interpret and display integer data in any one of four radixes: 
binary, decimal, hexadecimal, and octal. The default radix for both data entry 
and display is decimal for all languages except BLISS and MACRO. It is 
hexadecimal for BLISS and MACRO. You can use the SET RADIX and SET 
RADIX/OVERRIDE commands to change the default radix. 
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The DEPOSIT command sets the current entity built-in symbols %CURLOC 
and period (.) to the location denoted by the address expression specified. Logical 
predecessors (%PREVLOC and circumflex ( A )) and successors (%NEXTLOC and 
pressing the Return key) are based on the value of the current entity. 

Related commands: 

CANCEL TYPE/OVERRIDE 

EVALUATE 

EXAMINE 

(SET,SHOW,CANCEL) RADIX 
(SET,SHOW) TYPE 

Examples 

1. DBG> DEPOSIT I = 7 

This command deposits the value 7 into the integer variable I. 

2. DBG> DEPOSIT WIDTH = CURRENT_WIDTH + 24.80 

This command deposits the value of the expression CURRENT_WIDTH + 
24.80 into the real variable WIDTH. 

3. DBG> DEPOSIT STATUS = FALSE 

This command deposits the value FALSE into the Boolean variable STATUS. 


4. DBG> DEPOSIT PART_NUMBER = "WG-7619.3-84" 

This command deposits the string WG-7619.3-84 into the string variable 
PART.NUMBER. 

5 . DBG> DEPOSIT EMPLOYEE.ZIPCODE = 02172 

This command deposits the value 02172 into component ZIPCODE of record 
EMPLOYEE. 


6 . DBG> DEPOSIT ARR (8) = 35 
DBG> DEPOSIT A = 14 

The first DEPOSIT command deposits the value 35 into element 8 of array 
ARR. As a result, element 8 becomes the current entity. The second command 
deposits the value 14 into the logical predecessor of element 8, namely 
element 7. 


7. DBG> FOR I = 1 TO 4 DO (DEPOSIT ARR (I) = 0) 

This command deposits the value 0 into elements 1 to 4 of array ARR. 


8 . 


dbg> deposit COLOR = 3 

%DEBUG-E-OPTNOTALLOW, operator "DEPOSIT" 
data type 


DBG> 


not allowed on given 


The debugger alerts you when you try to deposit data of the wrong type 
into a variable (in this case, if you try to deposit an integer value into an 
enumerated type variable). The E (error) message severity indicates that the 
debugger does not make the assignment. 
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9. DBG> DEPOSIT VOLUME = - 100 

%DEBUG-I-IVALOUTBNDS, value assigned is out of bounds at or near 
DBG> 

The debugger alerts you when you try to deposit an out-of-bounds value into 
a variable (in this case a negative value). The I (informational) message 
severity indicates that the debugger does make the assignment. 

10. DBG> DEPOSIT/BYTE WORK = %HEX 21 

This command deposits the expression %HEX 21 into location WORK and 
converts it to a byte integer. 

11. DBG> DEPOSIT/OCTAWORD BIGINT = 111222333444555 

This command deposits the expression 111222333444555 into location 
BIGINT and converts it to an octaword integer. 

12. DBG> DEPOSIT/FLOAT BIGFLT = 1.11949*10**35 

This command converts 1.11949*10**35 to an Floating type value and 
deposits it into location BIGFLT. 

13. DBG> DEPOSIT/ASCII:10 WORK+20 = 'abcdefghij' 

This command deposits the string "abcdefghij" into the location that is 20 
bytes beyond that denoted by the symbol WORK. 

14. DBG> DEPOSIT/INSTR SUB2+2 = 'MOVL #20A f R0' 

This command deposits the instruction MOVL #20A,R0’ into the location 
SUB2 + 2 bytes. 

15. DBG> DEPOSIT/TASK VAR = %TASK 2 
DBG> EXAMINE/HEX VAR 

SAMPLE.VAR: 0016A040 
DBG> EXAMINE/TASK VAR 
SAMPLE.VAR: %TASK 2 
DBG> 

The DEPOSIT command deposits the Ada task value %TASK 2 into location 
VAR. The subsequent EXAMINE commands display the contents of VAR in 
hexadecimal format and as a task value, respectively. 
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DISABLE AST 

Disables the delivery of asynchronous system traps (ASTs) in your program. 

Format 

DISABLE AST 

Description 

The DISABLE AST command disables the delivery of ASTs in your program and 
thereby prevents interrupts from occurring while the program is running. If ASTs 
are delivered while the debugger is running (processing commands, and so on), 
they are queued and are delivered when control is returned to the program. 

The ENABLE AST command reenables the delivery of ASTs, including any 
pending ASTs (ASTs waiting to be delivered). 

Related commands: (ENABLE,SHOW) AST. 

Example 


DBG> DISABLE AST 
DBG> SHOW AST 
ASTs are disabled 
DBG> 

The DISABLE AST disables the delivery of ASTs in your program, as confirmed 
with the SHOW AST command. 
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DISPLAY 

Creates a new screen display or modifies an existing display. 

Format 

DISPLAY [display-name [AT window-spec] [display-kind] [,...]] 

Parameters 


display-name 

Specifies the display to be created or modified. 

If you are creating a new display, specify a name that is not already used as a 
display name. 

If you are modifying an existing display, you can specify any of the following 
entities: 

• A predefined display: SRC, OUT, PROMPT, INST, REG 

• A display previously created with the DISPLAY command 

• A display built-in symbol: 

%CURDISP 

%CURSCROLL 

%NEXTDISP 

%NEXTINST 

%NEXTOUTPUT 

%NEXTSCROLL 

%NEXTSOURCE 

You must specify this parameter unless you use /GENERATE (parameter 
optional), or /REFRESH (parameter not allowed). 

You can specify more than one display, each with an optional window specification 
and display kind. 

window-spec 

Specifies the screen window at which the display is to be positioned. You can 
specify any of the following entities: 

• A predefined window. For example, RH1 (right top half). See Appendix C. 

• A window definition previously established with the SET WINDOW command. 

• A window specification of the form (start-line, line-count ^start- 
column, column-count] ). The specification can include expressions which 
can be based on the built-in symbols %PAGE and %WIDTH (for example 
% WIDTH/4). 

If you omit the w-spec parameter, the screen position depends on whether you are 
specifying an existing display or a new display: 

• If you are specifying an existing display, the position of the display is not 
changed. 

• If you are specifying a new display, it is positioned at window HI or H2, 
alternating between HI and H2 each time you create another display. 
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disp-kind 

Specifies the display kind. Valid keywords are as follows: 

DO (.commands, . . . ]) Specifies an automatically updated output 

display. The commands are executed in the 
order listed each time the debugger gains 
control. Their output forms the contents of the 
display. If you specify more than one command, 
they must be separated by semicolons. 

INSTRUCTION Specifies an instruction display. If selected 

as the current instruction display with 
the SELECT/INSTRUCTION command, it 
displays the output from subsequent EXAMINE 
/INSTRUCTION commands. 

INSTRUCTION ( command ) Specifies an automatically updated instruction 

display. The command specified must be an 
EXAMINE/INSTRUCTION command. The 
instruction display is updated each time the 
debugger gains control. 

OUTPUT Specifies an output display. If selected as 

the current output display with the SELECT 
/OUTPUT command, it displays any debugger 
output that is not directed to another display. 

If selected as the current input display with the 
SELECT/INPUT command, it echoes debugger 
input. If selected as the current error display 
with the SELECT/ERROR command, it displays 
debugger diagnostic messages. 

REGISTER Specifies an automatically updated register 

display. The display is updated each time the 
debugger gains control. 

SOURCE Specifies a source display. If selected as the 

current source display with the SELECT 
/SOURCE command, it displays the output 
from subsequent TYPE or EXAMINE/SOURCE 
commands. 

SOURCE ( command ) Specifies an automatically updated source 

display. The command specified must be a 
TYPE or EXAMINE/SOURCE command. 

The source display is updated each time the 
debugger gains control. 

You cannot change the display kind of the PROMPT display. 

If you omit the disp-kind parameter, the display kind depends on whether you 

are specifying an existing display or a new display: 

• If you are specifying an existing display, the display kind is not changed. 

• If you are specifying a new display, an OUTPUT display is created. 
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Qualifiers 

/CLEAR 

Erases the entire contents of a specified display. Do not use /CLEAR when 
creating a new display. Do not use /GENERATE with /CLEAR. 

/DYNAMIC (default) 

/NODYNAMIC 

Controls whether a display automatically adjusts its window dimensions 
proportionally when the screen height or width is changed by a SET TERMINAL 
command. By default (/DYNAMIC), all user-defined and predefined displays, 
adjust their dimensions automatically. 

/GENERATE 

Regenerates the contents of a specified display. Only automatically generated 
displays are regenerated. These include DO displays, register displays, 
source ( cmd-list ) displays, and instruction ( cmd-list ) displays. The debugger 
automatically regenerates all these kinds of displays before each prompt. If 
no display is specified, regenerates the contents of all automatically generated 
displays. Do not use /GENERATE when creating a new display Do not use 
/CLEAR with /GENERATE. 

/HIDE 

Places a specified display at the bottom of the display pasteboard. This hides 
the specified display behind any other displays that share the same region of the 
screen. You cannot hide the PROMPT display. 

The /HIDE qualifier has the same effect as /PUSH. 

/MARK.CHANGE 
/NOMARK_CHANGE (default) 

Controls whether the lines that change in a DO display each time it is 
automatically updated are marked. When you use /MARK.CHANGE, any lines 
in which some contents have changed since the last time the display was updated 
are highlighted in reverse video. This qualifier is particularly useful when you 
want any variables in an automatically updated display to be highlighted when 
they change. 

The /NOMARK.CHANGE qualifier (default) specifies that any lines that change 
in DO displays are not to be marked. This qualifier cancels the effect of a 
previously entered /MARK.CHANGE qualifier on the specified display. 

This qualifier is not applicable to other kinds of displays. 

/POP (default) 

/NOPOP 

Controls whether a specified display is placed at the top of the display pasteboard, 
ahead of any other displays but behind the PROMPT display. By default (/POP),' 
the display is placed at the top of the pasteboard and hides any other displays 
that share the same region of the screen, except for the PROMPT display. This is 
the default action of the DISPLAY command. 

The /NOPOP qualifier preserves the order of all displays on the pasteboard (same 
effect as /NOPUSH). 
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/PROCESS[=(process-spec)] 

/NOPROCESS (default) 

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 

Controls whether the specified display is process specific—that is, whether the 
specified display is associated only with a particular process. The contents of a 
process-specific display are generated and modified in the context of that process. 
You can make any display process specific, except for the PROMPT display. 

The /PROCESS=(process-spec) qualifier causes the specified display to be 
associated with the specified process. You must include the parentheses. Use 
any of the following process-spec forms: 

[%PROCESS_NAME] process-name The VMS process name, if that 

name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 

[%PROCESS_NAME] "process-name" The VMS process name, if that name 

contains space or lowercase characters. 
You can also use apostrophes (') instead 
of quotation marks ("). 

%PROCESS_PID process Jd The VMS process identification number 

(PID, a hexadecimal number). 

%PROCESS_NUMBER proc-number The number assigned to a process 

when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. Do not 
specify a recursive symbol definition. 

The process after the visible process in 
the debugger’s circular process list. 

The process previous to the visible 
process in the debugger’s circular 
process list. 

The process whose call stack, register 
set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 

The /PROCESS qualifier causes the specified display to be associated with the 
process that was the visible process when the DISPLAY/PROCESS command was 
executed. 

The /NOPROCESS qualifier causes the specified display to always be associated 
with the visible process, which might change during program execution. This is 
the default behavior. 

If you do not specify /PROCESS, the current process-specific behavior (if any) of 
the specified display remains unchanged. 

See also /SUFFIX. 


(or %PROC proc-number) 

process-group-name 

%NEXT_PROCESS 

%PREVIOUS_PROCESS 

%VISIBLE_PROCESS 
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/PUSH 

/NOPUSH 

The /PUSH qualifier has the same effect as /HIDE. The /NOPUSH q ualifi er 
preserves the order of all displays on the pasteboard (same effect as /NOPOP). 

/REFRESH 

terminal screen. Do not specify any command parameters with 
/REFRESH. You can also use Ctrl/W to refresh the screen. 

/REMOVE 

Marks the display as being removed from the display pasteboard, so it is not 
shown on the screen unless you explicitly request it with another DISPLAY 
command. Although a removed display is not visible on the screen, it still exists 
and its contents are preserved. You cannot remove the PROMPT display. 

/SIZE:n 

Sets the maximum size of a display to n lines. If more than n lines are written to 
the display, the oldest lines are lost as the new lines are added. If you omit this 
qualifier, th© maximum siza of tho display is as follows i 

If you specify an existing display, the maximum size is unchanged. 

• If you are creating a display, the default size is 64 lines. 

For an output or DO display, /SIZErn specifies that the display should hold the 
n most recent lines of output. For a source or instruction display, n gives the 
number of source lines or lines of instructions that can be placed in the memory 
buffer at any one time. However, you can scroll a source display over the entire 
source code of the module whose code is displayed (source lines are paged into 
e buffer as needed). Similarly, you can scroll an instruction display over all of 
the instructions of the routine whose instructions are displayed (instructions are 
decoded from the image as needed). 


/SUFFIX[=process-identifier-type] 

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). Use this qualifier only directly after a display name. 

Appends a process-identifying suffix to a display name. The suffix denotes the 
visible process at the time the command was issued. This qualifier is used 
pnmarify in command procedures when specifying display definitions or key 
definitions that are bound to display definitions. 

Use any of the following process-identifier-type keywords: 

PROCESS_NAME 
PROCESSJNTUMBER 


PROCESS.PID 


The display-name suffix is the VMS process name. 

The display-name suffix is the process number (as shown 
in a SHOW PROCESS display). 

The display-name suffix is the VMS process 
identification number (PID). 


yc ’ u / pecif y /SUFFIX without a process-identifier-type keyword, the process 
identifier type used for the display-name suffix is, by default, the same as that 
used for the prompt suffix (see SET PROMPT/SUFFIX). 

See also /[NO]PROCESS. 
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Description 


The DISPLAY command can be used to create a display or modify an existing 
display. 

To create a display, specify a name that is not already used as a display name 
(the SHOW DISPLAY command identifies all existing displays). 

By default, the DISPLAY command places a specified display on top of the display 
pasteboard, ahead of any other displays but behind the PROMPT display, which 
cannot be hidden. The specified display thus hides the portions of other displays 
(except for the PROMPT display) that share the same region of the screen. 

See Appendix B for keypad-key definitions associated with the DISPLAY 
command. 

Related commands: 


Ctrl/W 

EXPAND 

MOVE 

SET PROMPT 

(SET,SHOW) TERMINAL 

(SET,SHOW,CANCEL) WINDOW 

SELECT 

(SHOW,CANCEL) DISPLAY 

Examples 

1. DBG> DISPLAY REG 

T his command shows the predefined register display, REG, at its current 
window location. 


2 . 


3. 


4. 


DBG> DISPLAY/PUSH INST 

This command pushes display INST to the bottom of the display pasteboard, 
behind all other displays. 

DBG> DISPLAY NEWDISP AT RT2 
DBG> SELECT/INPUT NEWDISP 

In this example, the DISPLAY command shows the user-defined display 
NEWDISP at the right middle third of the screen. The SELECT/INPUT 
command selects NEWDISP as the current input display. NEWDISP now 
echoes debugger input. 

DBG> DISPLAY DISP2 AT RS45 
DBG> SELECT/OUTPUT DISP2 

In this example, the DISPLAY command creates a display named DISP2 
essentially at the right bottom half of the screen, abovethePROMFr display, 
which is located at S6. This is an output display by default. The SELEC1 
/OUTPUT command then selects DISP2 as the current output display. 
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DBG> SET WINDOW TOP AT (1,8,45,30) 

DBG> DISPLAY NEWINST AT TOP INSTRUCTION 
DBG> SELECT/INST NEWINST 

In this example, the SET WINDOW command creates a window named TOP 
starting at line 1 and column 45, and extending down for 8 lines and to the 
right for 30 columns. The DISPLAY command creates an instruction display 
named NEWINST to be displayed through TOP. The SELECT/INST command 
selects NEWINST as the current instruction display. 

DBG> DISPLAY CALLS AT Q3 DO (SHOW CALLS) 

This command creates a DO display named CALLS at window Q3. Each time 
the debugger gains control from the program, the SHOW CALLS command 
is executed and the output is displayed in display CALLS, replacing any 
previous contents. 

DBG> DISPLAY/MARK EXAM AT Q2 DO (EXAMINE A,B,C) 

This command creates a DO display named EXAM at window Q2. The display 
shows the current values of variables A, B, and C whenever the debugger 
prompts for input. Any changed values are highlighted. 

DBG_3> DISPLAY/PROCESS 0UT_X AT S4 

This command makes display OUT_X specific to the visible process (process 
3) and puts the display at window S4. 

DBG__2> DISPLAY/PROCESS OUT_/SUFFIX AT S45 OUTPUT 

This command creates an output display at window S45. The /PROCESS 
qualifier, by default, makes the display specific to the visible process (process 
2, in this example). The /SUFFIX qualifier appends a process-identifying 
suffix, that denotes the visible process, to the display name OUT_. By 
default, the /SUFFIX qualifier appends the same process identifier suffix that 
appears on the prompt. Therefore, the full display name is OUT_2. 


; 


CD-71 












Debugger Command Dictionary 
DO 


DO 

Executes a debugger command in the context of one or more processes. 

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 

Format 

DO (command[; ... ]) 


Parameters 


command 

Specifies a debugger command that is to be 
processes specified. 


executed in the context of the 


Qualifiers 


/PROCESS=(process-spec[, ... ]) 

Specifies one or more processes in whose context the commands are executed. 
You must include the parentheses even if only one process is specified. If you do 
not specify /PROCESS, the commands are executed in the context of all processes 
(this effect is also achieved if you specify the asterisk (*) wildcard character for 


process-spec). 

Use any of the following forms: 
[%PROCESS_NAME] process-name 

[%PROCESS_NAME] "process-name' 

%PROCESS_PID processJd 

%PROCESS_NUMBER proc-number 
(or %PROC proc-number ) 

process-group-name 

%NEXT_PROCESS 

%PREVIOUS_PROCESS 


The VMS process name, if that 
name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 

The VMS process name, if that name 
contains space or lowercase characters. 
You can also use apostrophes (') instead 
of quotation marks ("). 

The VMS process identification number 
(PID, a hexadecimal number). 

The number assigned to a process 
when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. Do not 
specify a recursive symbol definition. 

The process after the visible process in 
the debugger’s circular process list. 

The process previous to the visible 
process in the debugger’s circular 
process list. 
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Description 


Examples 


%VISIBLE_PROCESS The process whose call stack, register 

set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


By default, commands are executed in the context of the visible process. The 
DO command enables you to execute commands in the context of one or more 
processes that are currently under debugger control (this is also referred to 
as "broadcasting" commands to processes). The DO command is equivalent to 

e "^ g o a o SET 1 PR0CESS/VISIBLE command for each process specified with the 
/PROCESS qualifier (or for all processes, if/PROCESS is not specified) and then 
entering the specified commands. 

To change the visible process, use the SET PROCESS command. 

When using the DO command, note that a hold condition in the visible process 
(as established with the SET PROCESS/HOLD command) is ignored. 

Related command: SET PROCESS. 


l. 


DBG_2> DO (SHOW CALLS) 

For %PROCESS_NUMBER 1 
module name routine 

*M0D4 SUB3 

For %PROCESS_NUMBER 2 
module name routine 

*M0D3 SUB1 

DBG 2> 


name 

line 

rel PC 

abs PC 


31 

0000001E 

0000041E 

name 

line 

rel PC 

abs PC 


4 

0000000B 

0000040B 


This command executes a SHOW CALLS command in the context of all 
processes that are currently under debugger control. 


DBG 3> D0/PR0CESS=(%PR0C 2,%PR0C 1) (EVAL/ADDR X;EXAM X) 

For %PROCESS_NUMBER 2 

%DEBUG-E-NOSYMBOL, symbol 'X' is not in the symbol table 
For %Process number 1 
512 

TEST\X: 1 
DBG_3> 

This command executes the two commands EVAL/ADDR X and EXAM X in 
the context of processes 2 and 1. 
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EDIT 


Invokes the editor established with the SET EDITOR command. If noSET 
EDITOR command was entered, invokes the VAX Language-Sensitive Editor, it 
that editor is installed on your system. 


Format 

EDIT [[module-name\] line-number] 


Parameters 


Specifies the name of the module whose source file is to be edited. If you specify a 
module name, you must also specify a line number. If you omit the module name 
parameter, the source file whose code appears in the current source display is 
chosen for editing. 

line-number ,. , , ,. A , 

A positive integer that specifies the source line on which the editor s cursor is 
initially placed. If you omit this parameter, the cursor is initially positioned 
at the beginning of the source line that is centered in the debugger scurrent 
source display, or at the beginning of line 1 if the editor was set to /NOSTART. 
POSITION (see the SET EDITOR command description). 


Qualifiers 


/EXIT 

/NOEXIT (default) . .. ... „ 

Controls whether you end the debugging session prior to invoking the editor. It 
you specify /EXIT, the debugging session is terminated and the editor is then 
invoked. If you specify /NOEXIT, the editing session is started and you return to 
your debugging session after terminating the editing session. 


Description 

If you have not specified an editor with the SET EDITOR command, the EDIT 
command invokes the VAX Language-Sensitive Editor in a spawned subprocess 
(if the VAX Language-Sensitive Editor is installed on your system). The typical 
(default) way to use the EDIT command is not to specify any parameters. In this 
case the editing cursor is initially positioned at the beginning of the line that 
is centered in the currently selected debugger source display (the current source 

display). 

The SET EDITOR command provides options for invoking different editors, either 
in a subprocess or through a callable interface. 

Related commands: 

(SET,SHOW) EDITOR 

(SET,SHOW,CANCEL) SOURCE 
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Examples 

1. DBG> EDIT 

In thi s example, the EDIT command spawns the VAX Language-Sensitive 
Editor in a subprocess to edit the source file whose code appears in the 
current source display. The editing cursor is positioned at the beginning of 
the line that was centered in the source display. 

2. DBG> EDIT SWAP\12 

In this example, the EDIT command spawns the VAX Language-Sensitive 
Editor in a subprocess to edit the source file containing the module SWAP, 
he editing cursor is positioned at the beginning of source line 12. 

3. DBG> SET EDITOR/CALLABLE EDT 

DBG> EDIT 

“ s th ? S , ET EDrrOB/CALLABLE.EOT command establishes 

that EDT is the default editor and is invoked through its callable interface 
(rather than spawned in a subprocess). The EDIT command invokes EDT 
to edit the source file whose code appears in the current source display. The 
editing cursor is positioned at the beginning of source line 1, because the 
default qualifier /NOSTART_POSITION applies to EDT. 
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ENABLE AST 

Enables the delivery of asynchronous system traps (ASTs) in your program. 

Format 

ENABLE AST 

Description 



rUnillllK, lliuiuuiilg ClAljr -- n- « ,, 

delivered while the debugger is running (processing commands, and so on), they 
are queued and are delivered when control is returned to the program. Delivery 
of ASTs in your program is initially enabled by default. 


Related commands: (DISABLE,SHOW) AST. 


Example 


DBG> ENABLE AST 
DBG> SHOW AST 
ASTs are enabled 
DBG> 


The ENABLE AST command enables the delivery of ASTs in your program, as 
confirmed with the SHOW AST command. 
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EVALUATE 


Evaluates a language expression in the current language (by default, the 
language of the module containing the main program). 

Format 


EVALUATE language-expression[, ... ] 


Parameters 

language-expression 

Specifies any valid expression in the current language. 

Qualifiers 


/BINARY 

Specifies that the result be displayed in binary radix. 


/CONDITION_VALUE 

Specifies that the expression be interpreted as a VMS condition value (the kind 
of condition value you would specify using the condition-handling mechanism). 

e message text corresponding to that condition value is then displayed. The 
specified value must be an integer value. 


/DECIMAL 

Specifies that the result be displayed in decimal radix. 


/HEXADECIMAL 

Specifies that the result be displayed in hexadecimal radix. 

/OCTAL 

Specifies that the result be displayed in octal radix. 


Description 


The debugger interprets the expression specified in an EVALUATE command as a 
anguage expression, evaluates it in the syntax of the current language and in the 
current radix, and displays its value as a literal (for example, an integer value) in 
the current language. 

The current language is the language last established with the SET LANGUAGE 
command. If no SET LANGUAGE command was entered, the current language 
is, by default, the language of the module containing the main program. 

If an expression contains symbols with different compiler generated types the 
expr^on USGS ^ type ‘ conversion rules of the current language to evaluate the 

The debugger can interpret and display integer data in any one of four radixes: 
bmary, decimal, hexadecimal, and octal. The current radix is the radix last 
established with the SET RADIX command. If no SET RADIX command was 
entered, the current radix for both data entry and display is, by default, decimal 

S r A niJfT ageS 6XCept BLISS and MACR0 - lt is hexadecimal for BLISS and 
?' a Can USe 3 radix quaIifier with the EVALUATE command (/BINARY 
/UC1AL, and so on) to display integer data in another radix. These qualifiers do’ 
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not affect how the debugger interprets the data you specify—that is, they override 
the current output radix, but not the input radix. 

The EVALUATE command sets the current value built-in symbols %CURVAL 
and backslash (\ ) to the value denoted by the specified expression. 

Debugger support for language-specific operators and constructs is described in 
Appendix E. 

Related commands: 

EVALUATE/ADDRESS 
(SET,SHOW) LANGUAGE 
(SET,SHOW,CANCEL) RADIX 
(SET,SHOW) TYPE 


Examples 


1. DBG> EVALUATE 100.34 * (14.2 + 7.9) 

2217.514 

DBG> 

This command uses the debugger as a calculator by multiplying 100.34 by 
(14.2 + 7.9). 

2. DBG> EVALUATE/OCTAL X 
00000001512 

DBG> 

This command evaluates the symbol X and displays the result in octal radix. 

3 . DBG> EVALUATE TOTAL + CURR_AMOUNT 
8247.20 

DBG> 

This command evaluates the sum of the values of two real variables, TOTAL 
and CURR_AMOUNT. 

4. DBG> DEPOSIT WILLING = TRUE 
DBG> DEPOSIT ABLE = FALSE 
DBG> EVALUATE WILLING AND ABLE 
False 

DBG> 

In this example, the EVALUATE command evaluates the logical AND of the 
current values of two Boolean variables, WILLING and ABLE. 

5 . DBG> EVALUATE COLOR'FIRST 
RED 

DBG> 

In this Ada example, this command evaluates the first element of the 
enumeration type COLOR. 
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EVALUATE/ADDRESS 


Evaluates an address expression and displays the result as a memory address or 
a register name. 

Format 

EVALUATE/ADDRESS address-expression[, ... ] 

Parameters 


address-expression 

Specifies an address expression of any valid form (for example, 
variable name, a label, a line number, and so on). 


a routine name, a 


Qualifiers 


/BINARY 

Specifies that the memory address is displayed in binary radix. 

/DECIMAL 

Specifies that the memory address is displayed in decimal radix. 

/HEXADECIMAL 

Specifies that the memory address is displayed in hexadecimal radix. 

/OCTAL 

Specifies that the memory address is displayed in octal radix. 


Description 


T ^f EVALUATE/ADDRESS command enables you to determine the memory 
address or register associated with an address expression. 

The debugger can interpret and display integer data in any one of four radixes- 
binary, decimal, hexadecimal, and octal. The default radix for both data entry and 

? SP nf T aa deC iTA f ° r a11 kn « ua 8 e8 exce P t BE ISS and MACRO. It is hexadecimal 
tor BLlbb and MACRO. You can use a radix qualifier with the EVALUATE 

command (/BINARY, /OCTAL, and so on) to display address values in another 
ra ix. These qualifiers do not affect how the debugger interprets the data you 
specify—that is, they override the current output radix, but not the input radix. 

ttvaT t V t a 1 ^ / A f r, a J^o o le iS currently stored in a «*iater instead of memory, the 
EVALUATE/ADDRESS command identifies the register. The radix qualifiers have 
no effect m that case. 

l h A ™E UATE/ADDRESS command sets the current entity built-in symbols 
votURLOC and period (.) to the location denoted by the address expression 
Smfvtt Logical predecessors (%PREVLOC and circumflex ( a )) and successors 

(%NEXTLOC and pressing the Return key) are based on the value of the current 
entity. 
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Related commands: 

EVALUATE 

(SET,SHOW,CANCEL) RADIX 
SHOW SYMBOL/ADDRESS 
SYMBOLIZE 


Examples 

1 DBG> EVALUATE/ADDRESS MODNAMEULINE 110 
3942 
DBG> 

This command displays the memory address denoted by the address 
expression MODNAMEX %LINE 110. 

2. DBG> EVALUATE/ADDRESS/HEX A,B,C 
000004A4 

000004AC 

000004A0 

DBG> 

This command displays the memory addresses denoted by the address 
expressions A, B, and C in hexadecimal radix. 

3. DBG> EVALUATE/ADDRESS X 
M0D3\%R1 

DBG> 

T his command indicates that variable X is associated with register Rl. X is a 
nonstatic (register) variable. 


CD-80 






Debugger Command Dictionary 

EXAMINE 


EXAMINE 


Format 

Displays the current value of a program variable. More generally, displays the 
value of the entity denoted by an address expression. 


EXAMINE [address-expression[:address-expression] [,...]] 

Parameters 

address-expression 


Qualifiers 

Specifies an entity to be examined. With high-level languages, this is typically the 
name of a variable and can include a pathname to specify the variable uniquely. 
More generally, an address expression can also be a memory address or a register 
and can be composed of numbers (offsets) and symbols, as well as one or more 
operators, operands, or delimiters. Appendix D identifies the debugger’s built-in 
symbols for the VAX registers and identifies the operators that can be used in 
address expressions. 

If you specify the name of an aggregate variable (a composite data structure 
such as an array or record structure) the debugger displays the values of all 
e ements. For an array, the display shows the subscript (index) and value of each 

array element. For a record, the display shows the name and value of each record 
component. 

To specify an individual array element, array slice, or record component, use the 
syntax of the current language. 

If you specify a range of entities, the value of the address expression that denotes 
the first entity in the range must be less than the value of the address expression 
at denotes the last entity in the range. The debugger displays the entity 
specified by the first address expression, the logical successor of that address 
expression, the next logical successor, and so on, until it displays the entity 
specified by the last address expression. You can specify a list of ranges by 
separating ranges with a comma. 

See Chapter 11 and the descriptions of the /TMASK, /FMASK, and /OPERANDS 
qualifiers for information that is specific to vector registers and vector 
instructions. 

/ASCIC 

Interprets each examined entity as a counted ASCII string preceded by a 1-byte 
count field that gives the length of the string. The string is then displayed. The 
/AC qualifier is also accepted. 

/ASCID 

Interprets each examined entity as the address of a string descriptor pointing 
to an ASCII string. The CLASS and DTYPE fields of the descriptor are not 
checfced, but the LENGTH and POINTER fields provide the character length and 
address of the ASCII stnng. The string is then displayed. The /AD qualifier is 
also accepted. 
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Interprets and displays each examined entity as an ASCII string of length n bytes 
in characters). If n is omitted, the debugger attempts to determine a length from 
the type of the address expression. 

/ASCIW 

Interprets each examined entity as a counted ASCII string preceded by a 2-byte 
count field that gives the length of the string. The string is then displayed. The 
/AW qualifier is also accepted. 

Interprets each examined entity as a zero-terminated ASCII string. The ending 
zero byte indicates the end of the string. The string is then displayed. The /AZ 
qualifier is also accepted. 

/BINARY 

Displays each examined entity as a binary integer. 

/BYTE 

Displays each examined entity in the byte integer type (length 1 byte). 

/CONDITION VALUE , , ,. . 

Interprets each examined entity as a condition-value return status and displays 

the message associated with that return status. 

Displays each examined entity in the D_floating type (length 8 bytes). Values of 
type D.floating can range from .29 * 1CT 38 to 1.7 * 10 38 with approximately 16 
decimal digits precision. 

Interprets^each examined entity as a quadword integer (length 8 bytes) containing 
the internal VMS representation of date and time. Displays the value in the 
format dd-mmm-yyyy hh:mm:ss.xx. 

/DECIMAL 

Displays each examined entity as a decimal integer. 

/DEFAULT 

Displays each examined entity in the default radix. 

Displays each examined entity in the Floating type (length 4 bytes). Values 
of type Floating can range from .29 * 1(T 38 to 1.7 * 10 38 with approximately 7 

decimal digits precision. 

/FMASK[=(mask-address-expression)] 

Applies to vectorized programs. 

See /TMASK. 

Slplayflach examined entity in the G_floating type (length 8 bytes). Values of 
type G_floating can range from .56 * 10" 308 to .9 * 10 308 with approximately 15 
decimal digits precision. 
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/H FLOAT 


Displays each examined entity in the H_floating type (length 16 bytes). Values of 

type H floating can range from .84 * 1(T 4932 to .59 * 10 4932 with approximately 33 
decimal digits precision. 


/HEXADECIMAL 

Displays each examined entity as a hexadecimal integer. 

/INSTRUCTION 

Displays each examined entity as a VAX assembly-language instruction (variable 
length, depending on the number of instruction operands and the kind of 
addressing modes used). See also /OPERANDS. 

In screen mode, the output of an EXAMINE/INSTRUCTION command is directed 
at the current instruction display, if any, not at an output or DO display. The 
arrow in the instruction display points to the examined instruction. 

/LINE (default) 

/NOLINE 

S^ols whether program locations are displayed in terms of line numbers 
(%LINE x) or as routine-name + byte-offset. By default (/LINE), the debugger 
symbolizes program locations in terms of line numbers. 

/LONGWORD 

Displays each examined entity in the longword integer type (length 4 bytes). This 
is the default type for program locations that do not have a compiler generated 


/OCTAL 

Displays each examined entity as an octal integer. 

/OCTAWORD 

Displays each examined entity in the octaword integer type (length 16 bytes). 


/OPERANDS[=keyword] 

Displays operand information associated with an examined instruction (displays 
each operand’s address and its contents, using the operand’s data type). The 
keywords BRIEF and FULL vary the amount of information displayed about any 
nonregister operands. The default is /OPERANDS=BRIEF. 


Use /OPERANDS only when examining the instruction at the current PC value 
(for example, EXAMINE/OPERANDS .0\%PC). Examining the operands of 
an instruction that is not at the current PC value can give erroneous results 
because the state of the machine (the contents of the registers) is not set up for 
that instruction. 

In screen mode, operand information is directed at the current output display. 

When you examine the operands of a vector instruction, any operand-element 
Sf*®*** mi ? h i, be associated with that instruction is performed by default. 

e /TMASK and /FMASK qualifiers enable you to specify some other mask The 
current value of the vector length register (VLR) limits the highest element of a 
vector register that you can examine. 


See also the SET MODE [NOJOPERANDS^cyiW command. It enables you 
to set a default level for the amount of operand information displayed when 
examining instructions. 
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/PACKED:n , 

Interprets each examined entity as a packed decimal number. The value ot n is 
the number of decimal digits. Each digit occupies one nibble (4 bits). 

Displays each examined entity in PSL (processor status longword) format. 

/PSW 

Displays each examined entity in PSW (processor status word) format. The /PSW 
qualifier is like /PSL except that only the low order word (2 bytes) is displayed. 

/QUADWORD „ , o v.i 

Displays each examined entity in the quadword integer type (length 8 bytes). 

/SOURCE 

Displays the source line corresponding to the location of each examined entity. 

The examined entity must be associated with a machine code instruction and, 
therefore, must be a line number, a label, a routine name, or the memory address 
of an instruction. The examined entity cannot be a variable name or any other 
address expression that is associated with data. 

In screen mode, the output of an EXAMINE/SOURCE command is directed at the 
current source display, if any, not at an output or DO display- The arrow in t e 
source display points to the source line associated with the last entity specified 
(or the last one specified in a list of entities). 

/SYMBOLIC (default) 

Controls whether symbolization occurs. By default (/SYMBOLIC), the debugger 
symbolizes all addresses, if possible; that is, it converts numeric addresses into 
their symbolic representation. If you specify /NOSYMBOLIC, the debugger 
suppresses symbolization of entities you specify as absolute Tr 

specify entities as variable names, symbolization still occurs. The /NOSYMBOL 
qualifier is useful if you are interested in identifying numeric addresses rather 
than their symbolic names (if symbolic names exist for those addresses). If you 
specify /NOSYMBOLIC, command processing might speed up somewhat, because 
the debugger does not need to convert numbers to names. 

/TASK 

Applies to tasking (multithread) programs. 

Interprets each examined entity as a task (thread) object and displays the task 
value (the name or task ID) of that task object. 

When examining a task object, use the /TASK qualifier only if the programming 
language does not have built-in tasking services. 

/TMASK[=(mask-address-expresslon)] 

/FMASK[=(mask-address-expression)] 

These qualifiers apply to vectorized programs. 

These qualifiers enable you to specify a mask in order to display certain elements 
of a vector register (VO to V15), or of an array in memory, while not displaying 

other elements. 

For example, when you examine the operands of a vector instruction (by using 
the /OPERANDS qualifier), these qualifiers enable you to override any operand- 
element masking that might be associated with that instruction. 


CD-84 




Debugger Command Dictionary 

EXAMINE 


Description 


The /TMASK qualifier applies the EXAMINE command only to the elements of 
rf 1 2SSX ° r ar y a / that correspond to the set bits (bit value: 1) of the mask. 
The /FMASK qualifier applies the EXAMINE command only to the elements that 
correspond to the clear bits (bit value: 0) of the mask. The current value of the 
vector length register (VLR) limits the highest register element that you can 
examine but not the highest array element. 

y0U do not specify a mask address expression with /TMASK or 
/rMASK, the vector mask register (VMR) is used. That is, the EXAMINE 
command is applied only to the elements of the vector register or array that 

/FMASK^of VMR ( “ ^ CaSe of/TMASK) or clear *>*8 On the case of 

If you specify a mask address expression with /TMASK or /FMASK, the value at 
that address is used as the mask, subject to the following conventions: 

You must use parentheses around the address expression. 

P 1 ® number of mask elements limits the number of register or array elements 
that you can examine. 

• If the mask address expression denotes a Boolean array, its values are used 
as the mask, in the same basic way that VMR is used in the default case. 

• If the mask address expression denotes a non-Boolean array, the least 
significant bit value of each array element is used as the mask for the 
corresponding element of the register or target array. 

• If the mask address expression denotes a Boolean scalar type, its value is 
used as the mask for the first element of the register or target array. No 
other elements are examined. 

If the mask address expression denotes any other type, its least significant bit 
value is used as the mask for the first element of the register or target array. 
No other elements are examined. 

For a multi-element mask, the lowest specified element of the mask is applied 
to the lowest specified element of the register or target array. 

/TYPE=(name) 

Interprets and displays each examined entity according to the type specified 
by name (which must be the name of a variable or data type declared in the 
program). This enables you to specify a user-declared type. 

/WORD 

Displays each examined entity in the word integer type (length 2 bytes). 


The EXAMINE command displays the entity at the location denoted by an 
address expression. The command can be used to display the contents of any 
memory location or register that is accessible in your program. For high-level 
languages the command is used mostly to obtain the current value of a variable 
(an integer, real, string, array, record, and so on). 

The debugger recognizes the compiler-generated types associated with symbolic 
address expressions (symbolic names declared in your program). Symbolic 
address expressions include the following entities: 

Variable names. When specifying a variable with the EXAMINE command 

use the same syntax that is used in the source code. 
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. Routine names, labels, and line numbers. These are associated with VAX 
instructions. You can examine instructions using the same techniques as 
when examining variables. 

In general, when you enter an EXAMINE command, the debugger evaluates 
the address expression specified to yield a program location. The debugger t 
displays the value stored at that location as follows: 

• If the location has a symbolic name, the debugger formats the value according 
to the compiler generated type associated with that symbol—that is, as a 
variable of a particular type or as a VAX instruction. 

. If the location does not have a symbolic name (and, therefore no associated 
compiler generated type) the debugger formats the v ^e in the type longword 
integer by default. This means that, by default, the EXAMINE command 
displays the contents of these locations as longword (4-byte) integer values. 

See Chapter 11 and the descriptions ot the /TMASK, /FMASK, and /OPERANDS 
qualifiers for information that is specific to vector registers and vector 
instructions. 

There are several ways of changing the type associated with a program location 
so that you can display the data at that location in another data format: 

• To change the default type for all locations that do not have a symbolic name, 
you can specify a new type with the SET TYPE command. 

. To change the default type for all locations (both those that do and do not 
have a symbolic name), you can specify a new type with the SET iYPfc 
/OVERRIDE command. 

• To override the type currently associated with a particular location for the 
duration of a single EXAMINE command, you can specify a new typeby 
means of a type qualifier (/ASCII:n, /BYTE, /TYPE =(name), and so on). Most 
of the EXAMINE command qualifiers are type qualifiers. 

The debugger can interpret and display integer data in any one of four radl «* : 
binary, decimal, hexadecimal, and octal. The default radix for both data entry and 
display is decimal for all languages except BLISS and MACRO. It is hexadecim 
for BLISS and MACRO. The EXAMINE command has four radix qualifiers 
(/BINARY, /DECIMAL, /HEXADECIMAL, /OCTAL) ^enable you to display 
data in another radix. You can also use the SET RADIX and SET RADIX 
/OVERRIDE commands to change the default radix. 

In addition to the type and radix qualifiers, the EXAMINE command has 
qualifiers for other purposes: 

• The /SOURCE qualifier enables you to identify the line of source code 
corresponding to a line number, routine name, label, or any other address 
expression that is associated with an instruction rather than data. 

• The /[NO]LINE and /[NO]SYMBOL qualifiers enable you to control the 
symbolization of address expressions. 

The EXAMINE command sets the current entity built-in symbols %CURLOC 
and period (.) to the location denoted by the address expression specified Logica 
predecessors (%PREVLOC and circumflex ( A )) and successors (%NEXTLOC and 
pressing the Return key) are based on the value of the current entity. 
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Debugger Command Dictionary 

EXAMINE 


Related Commands: 

CANCEL TYPE/OVERRIDE 

DEPOSIT 

EVALUATE 

SET MODE [NOJOPERANDS 
SET MODE [NOJSYMBOLIC 
(SET,SHOW,CANCEL) RADIX 
(SET,SHOW) TYPE 


1. DBG> EXAMINE COUNT 
SUB2\C0UNT: 27 
DBG> 


This command displays the value of the integer variable COUNT, 
SUB2. 


in module 


2. DBG> EXAMINE PART NUMBER 
INVENTORY\PARTNUMBER: "LP-3592 6-84" 

DBG> 

This command displays the value of the string variable PART_NUMBER. 

3. DBG> EXAMINE SUB1\ARR3 


SUB1\ARR3 

(1,1) 

27.01000 

(1,2) 

31.01000 

(1,3) 

12.48000 

(2,1) 

15.08000 

(2,2) 

22.30000 

(2,3) 

18.73000 


DBG> 


aTTOi COi r^o d dlsplays the value of a11 elements in array ARR3, in module 
ARR3 is a 2 by 3 element array of real numbers. 


4. DBG> EXAMINE SUB1\ARR3(2,1:3) 

SUB1\ARR3 

(2.1) : 15.08000 

(2.2) : 22.30000 

(2.3) : 18.73000 

DBG> 

disp ^ ays v& iue of the elements in a slice of array 
SUB1\ARR3. The slice includes "columns" 1 to 3 of "row" 2. 


DBG> EXAMINE VALVES.INTAKE.STATUS 
MONITOR\VALVES. INTAKE. STATUS: OFF 
DBG> 


This command displays the value of the nested record 
VALVES.INTAKE.STATUS in module MONITOR. 


component 


dbg> examine/source swap 

module MAIN 

47: procedure SWAP(X,Y: in out INTEGER) is 


This command displays the source line in which routine SWAP is declared 
(the location of routine SWAP). 
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7. 


DBG> DEPOSIT/ASCII:7 WORK+20 = 'abcdefg' 
DBG> EXAMINE/ASCII:7 WORK+20 
DETAT\WORK+20: "abcdefg" 

DBG> EXAMINE/ASCII:5 WORK+20 
DETAT\WORK+20: "abcde" 


DBG> 

In this example, the DEPOSIT command deposits the entity 'abcdefg' as 
an ASCII string of length 7 bytes into the location that is 20 bytes beyon 
Aeication dieted b?*e s£ibol WORK. The first EXAMINE command 
displays the value of the entity at that location as an ASCII stnng of length 
7 bytes (abcdefg). The second EXAMINE command displays the value of the 
entitv at that location as an ASCII string of length 5 bytes (abcde). 


8 . 


DBG> EXAMINE/INST MAIN+2 

MAIN\MAIN+02: moval L a MAIN A,R11 


DBG> 

This command displays the contents of the location that is 2 bytes beyond the 
location denoted by the symbol MAIN as an instruction (MOVAL). 


9 . DBG> EXAMINE/OPERANDS=FULL .0\%PC 
X\X$START+OC: MOVL B a 04(R4),R7 


B A 04(R4) 


R7 


MUVL d ... 

R4 contains X\X$START\M (address 00001054), 
B A 04(00001054) evaluates to X\X$START\K 
(address 00001058), which contains 00000016 
R7 contains 00000000 


DBG> 


This command displays the instruction (MOVL) at the current PC value The 
/OPERANDS qualifier with the keyword FULL displays the maximum level of 
onerand information. 


10 . 


DBG> SET RADIX HEXADECIMAL 
DBG> EVALUATE/ADDRESS WORKDATA 


0000086F 

DBG> EXAMINE/SYMBOLIC 0000086F 

MOD3\WORKDATA: 03020100 

DBG> EXAMINE/NOSYMBOLIC 0000086F 

0000086F: 03020100 

DBG> 


In this example, the EVALUATE/ADDRESS command indicates that the 
memory address of variable WORKDATA is 0000086F, hexadecimal. The 
two EXAMINE commands display the value contained at that address using 
the /fNO]SYMBOL qualifier to control whether the address is symbolized to 


WORKDATA. 


11. DBG> EXAMINE/HEX FIDBLK 
FDEX1$MAIN\FIDBLK 

(1): 00000008 

( 2 ): 00000100 

(3): OOOOOOAB 

DBG> 

This command displays the value of the array variable FIDBLK in 
hexadecimal radix. 
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' EXAMINE/DECIMAL/WORD NEWDATA:NEWDATA+6 
SUB2\NEWDATA: 256 
SUB2\NEWDATA+2: 770 

SUB2\NEWDATA+4: 1284 

SUB2\NEWDATA+ 6: 1798 

DBG> 


ihis c° m man d displays, in decimal radix, the values of word integer entities 
NEWDATA ^6 bytes ^ ** ^ ° f locations denoted b y NEWDATA to 


DBG> EXAMINE/TASK SORT INPUT 
MOD3\SORT INPUT: %TASK 12 
DBG> 

This command displays the task ID of a task object named SORT_INPUT. 
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EXIT 

Ends a debugging session, or terminates one or more processes of a multiprocess 
program, allowing any application-declared exit handlers to run. 

If used within a command procedure or DO clause and no process is specified, 
exits the command procedure or DO clause at that point. 

Format 

EXIT [process-spec[, ... ]] 


Parameters 


This parameter applies to a multiprocess debugging configuration (when 
DBG$PROCESS has the value MULTIPROCESS). 

Specifies a process. Use any of the following forms: 

The VMS process name, if that 
name contains no space or lowercase 


[%PROCESS_NAME] process-name 

[%PROCESS_NAME] " process-name" 

%PROCESS_PID process Jd 

%PROCESS_NUMBER proc-number 
(or %PROC proc-number) 

process-group-name 

%NEXT_PROCESS 

%PREVIOUS_PROCESS 

%VISIBLE_PROCESS 

You can also use 


characters. The process name can 
include the asterisk (*) wildcard 
character. 

The VMS process name, if that name 
contains space or lowercase characters. 
You can also use apostrophes (') instead 
of quotation marks ("). 

The VMS process identification number 
(PID, a hexadecimal number). 

The number assigned to a process 
when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. Do not 
specify a recursive symbol definition. 
The process after the visible process in 
the debugger’s circular process list. 

The process previous to the visible 
process in the debugger’s circular 
process list. 

The process whose call stack, register 
set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


the asterisk (*) wildcard character to specify all processes. 
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Description 

The EXIT command is one of the four debugger commands that can be used to 
execute your program (the others are CALL, GO, and STEP). 

Ending a Debugging Session 

To end a debugging session, enter the EXIT command at the debugger prompt 
without specifying any parameters. This causes orderly termination of the 
session: the prop-am’s application-declared exit handlers (if any) are executed, 
the debugger exit handler is executed (closing log files, restoring the screen and 
keypad states, and so on), and control is returned to the command interpreter. 
You cannot then continue to debug your program by entering the DCL commands 
DEBUG or CONTINUE. To restart the debugger, you must run the program 
again. 

Because EXIT runs any application-declared exit handlers, you can set 
breakpoints in such exit handlers, and the breakpoints are triggered upon typing 
EXIT. EXIT can thus be used to debug your exit handlers. 

To end a debugging session without running any application-declared exit 
handlers, use the QUIT command instead of EXIT. 

Using the EXIT Command in Command Procedures and DO Clauses 

When the debugger executes an EXIT command (without any parameters) in 
a command procedure, control returns to the command stream that invoked 
the command procedure. A command stream can be the terminal, an outer 
(containing) command procedure, or a DO clause in a command or screen display 
definition. For example, if the command procedure was invoked from within a DO 
clause, control returns to that DO clause, where the debugger executes the next 
command (if any remain in the command sequence). 

When the debugger executes an EXIT command (without any parameters) in a 
DO clause, it ignores any remaining commands in that clause and displays its 
prompt. 

Terminating Specified Processes 

If you are using the multiprocess debugging configuration to debug a multiprocess 
program (if the logical name DBG$PROCESS has the value MULTIPROCESS), 
you can use the EXIT command to terminate specified processes without ending 
the debugging session. The same techniques and behavior apply, whether you 
enter the EXIT command at the prompt or use it within a command procedure or 
DO clause. 

To terminate one or more processes, enter the EXIT command, specifying these 
processes as parameters. This causes orderly termination of the images in these 
processes, executing any application-declared exit handlers associated with these 
images. Subsequently, the specified processes are no longer identified in a SHOW 
PROCESS/ALL display. If any specified processes were on hold, as the result of a 
SET PROCESS/HOLD command, the hold condition is ignored. 

When the specified processes begin to exit, any unspecified process that is not on 
hold begins execution. After execution is started, the way in which it continues 
depends on whether the SET MODE [NOJINTERRUPT command was entered 
previously. By default (SET MODE INTERRUPT), execution continues until it 
is suspended in any process. At that point, execution is interrupted in any other 
processes that were executing images, and the debugger prompts for input. 
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QUIT 

Ends a debugging session, or terminates one or more processes of a multiprocess 
program (like EXIT), but without allowing any application-declared exit handlers 
to run. 

If used within a command procedure or DO clause and no process is specified, 
exits the command procedure or DO clause at that point. 

Format 

QUIT [process-spec[, ... ]] 

Parameters 


process-spec 

This parameter applies to a multiprocess debugging configuration (when 
DBG$PROCESS has the value MULTIPROCESS). 

Specifies a process. Use any of the following forms: 


[%PROCESS_NAME] process-name 

[%PROCESS_NAME] "process-name' 

%PROCESS_PID processed 

%PROCESS_NUMBER proc-number 
(or %PROC proc-number) 

process-group-name 

%NEXT_PROCESS 

%PREVIOUS_PROCESS 

%VISIBLE_PROCESS 


The VMS process name, if that 
name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 

The VMS process name, if that name 
contains space or lowercase characters. 
You can also use apostrophes (') instead 
of quotation marks ( " ). 

The VMS process identification number 
(PID, a hexadecimal number). 

The number assigned to a process 
when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. Do not 
specify a recursive symbol definition. 

The process after the visible process in 
the debugger’s circular process list. 

The process previous to the visible 
process in the debugger’s circular 
process list. 

The process whose call stack, register 
set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


You can also use the asterisk (*) wildcard character to specify all processes. 
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Description 

The QUIT command is like the EXIT command, except that QUIT does not cause 
your program to execute and, therefore, does not execute any application-declared 
exit handlers in your program. 

Ending a Debugging Session 

To end a debugging session, enter the QUIT command at the debugger prompt 
without specifying any parameters. This causes orderly termination of the 
session: the debugger exit handler is executed (closing log files, restoring the 
screen and keypad states, and so on), and control is returned to the command 
interpreter. You cannot then continue to debug your program by entering the 
DCL commands DEBUG or CONTINUE. To restart the debugger, you must run 
the program again. 

Using the QUIT Command in Command Procedures and DO Clauses 

When the debugger executes a QUIT command (without any parameters) in 
a command procedure, control returns to the command stream that invoked 
the command procedure. A command stream can be the terminal, an outer 
(containing) command procedure, or a DO clause in a command or screen display 
definition. For example, if the command procedure was invoked from within a DO 
clause, control returns to that DO clause, where the debugger executes the next 
command (if any remain in the command sequence). 

When the debugger executes a QUIT command (without any parameters) in a 
DO clause, it ignores any remaining commands in that clause and displays its 
prompt. 

Terminating Specified Processes 

If you are using the multiprocess debugging configuration to debug a multiprocess 
program (if the logical name DBG$PROCESS has the value MULTIPROCESS), 
you can use the QUIT command to terminate specified processes without ending 
the debugging session. The same techniques and behavior apply, whether you 
enter the QUIT command at the prompt or use it within a command procedure or 
DO clause. 

To terminate one or more processes, enter the QUIT command, specifying these 
processes as parameters. This causes orderly termination of the images in these 
processes without executing any application-declared exit handlers associated 
with these images. Subsequently, the specified processes are no longer identified 
in a SHOW PROCESS/ALL display. 

In contrast to the EXIT command, the QUIT command does not cause any process 
to start execution. 

Related commands: 

@ (Execute Procedure) 

Ctrl/C 

Ctrl/Y 

Ctrl/Z 

EXIT 

SET ABORT.KEY 
SET PROCESS 
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Examples 

1 DBG> QUIT 
$ 

This command, when entered from the prompt, ends the debugging session 
and returns you to DCL command level. 

2. J0NES_1> QUIT %NEXT_PROCESS, %PROCESS_NAME J0NES_3, %PR0C 5 
J0NES_1> 

This command causes orderly termination of three processes of a multiprocess 
program: the process after the visible process on the process list, process 
JONES_3, and process 5. Control is returned to the debugger after the 
specified processes have exited. 
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REPEAT 


Executes a sequence of commands a specified number of times. 


Format 

REPEAT language-expression DO (command[; ... ]) 


Parameters 


language-expression 

Denotes any expression in the currently set language that evaluates to a positive 
integer. 

command 

Specifies a debugger command. If you specify more than one command, they must 
be separated by semicolons. 

Description 

The REPEAT command is a simple form of the FOR command. The REPEAT 
command executes a sequence of commands repetitively a specified number of 
times, without providing the options for establishing count parameters that the 
FOR command does. 

Related commands: 

EXITLOOP 

FOR 

WHILE 


Example 

DBG> REPEAT 10 DO (EXAMINE Y; STEP) 

This command line sets up a loop that issues a sequence of two commands 
(EXAMINE Y, then STEP) 10 times. 
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SAVE 


Preserves the contents of an existing screen display in a new display. 


Format 

SAVE old-display AS new-display [,...] 


Parameters 


old-display 

Specifies the display whose contents are saved. You can specify any of the 
following entities: 

• A predefined display: SRC, OUT, PROMPT, INST, REG 

• A display previously created with the DISPLAY command 

• A display built-in symbol: 

%CURDISP 

%CURSCROLL 

%NEXTDISP 

%NEXTINST 

%NEXTOUTPUT 

%NEXTSCROLL 

%NEXTSOURCE 

new-display 

Specifies the name of the new display to be created. This new display then 
receives the contents of the old-disp display. 


Qualifiers 

/SUFFIX[=process-identifier-type] 

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). Use this qualifier only directly after a display name. 

Appends a process-identifying suffix to a display name. The suffix denotes the 
visible process at the time the command was issued. This qualifier is used 
primarily in command procedures when specifying display definitions or key 
definitions that are bound to display definitions. 

Use any of the following process-identifier-type keywords: 

PROCESS_NAME The display-name suffix is the VMS process name. 

PROCESS_NUMBER The display-name suffix is the process number (as shown 

in a SHOW PROCESS display). 

PROCESS_PID The display-name suffix is the VMS process 

identification number (PID). 

If you specify /SUFFIX without a process-identifier-type keyword, the process 
identifier type used for the display-name suffix is, by default, the same as that 
used for the prompt suffix (see SET PROMPT/SUFFIX). 
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Description 

The SAVE command enables you to save a "snapshot" copy of an existing display 
in a new display for later reference. The new display is created with the same 
text contents as the existing display. In general, the new display is given all the 
attributes or characteristics of the old display except that it is removed from the 
screen and is never automatically updated. You can later recall the saved display 
to the terminal screen with the DISPLAY command. 

When you use the SAVE command, only those lines that are currently stored 
in the display’s memory buffer (as determined by the /SIZE qualifier on the 
DISPLAY command) are stored in the saved display. However, in the case of 
a saved source or instruction display, you can also see any other source lines 
associated with that module or any other instructions associated with that 
routine (by scrolling the saved display). 

You cannot save the PROMPT display. 

Related commands: 

DISPLAY 

EXITLOOP 

Example 

DBG> SAVE REG AS OLDREG 

This command saves the contents of the display named REG into the newly 
created display named OLDREG. 
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SCROLL 

Scrolls a screen display to make other parts of the text visible through the display 
window. 

Format 

SCROLL [display-name] 

Parameters 

display-name 

Specifies a display to be scrolled. You can specify any of the following entities: 

• A predefined display: SRC, OUT, PROMPT, INST, REG 

• A display previously created with the DISPLAY command 

• A display built-in symbol: 

%CURDISP 

%CURSCROLL 

%NEXTDISP 

%NEXTINST 

%NEXTOUTPUT 

%NEXTSCROLL 

%NEXTSOURCE 

If you do not specify a display, the current scrolling display, as established by the 
SELECT command, is chosen. 


Qualifiers 

/BOTTOM 

Scrolls down to the bottom of the display’s text. 


/DOWN:[n] J . iU 

Scrolls down over the display’s text by n lines to reveal text further down in the 
display. If n is omitted, the display is scrolled by approximately 3/4 of its window 
height. 

/LEFT : [n] „ 

Scrolls left over the display’s text by n columns to reveal text beyond the left 
window border. You cannot scroll past column 1. If n is omitted, the display is 
scrolled left by 8 columns. 


/nivai i i |«i ij _ . , , 

Scrolls right over the display’s text by n columns to reveal text beyond the right 
window border. You cannot scroll past column 255. If n is omitted, the display is 
scrolled right by 8 columns. 

/SUFFIX[=process-identifier-type] 

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). Use this qualifier only directly after a display name. 
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Appends a process-identifying suffix to a display name. The suffix denotes the 
visible process at the time the command was issued. This qualifier is used 
primarily in command procedures when specifying display definitions or key 
definitions that are bound to display definitions. 

Use any of the following process-identifier-type keywords: 

PROCESS_NAME The display-name suffix is the VMS process name. 

PROCESS_NUMBER The display-name suffix is the process number (as shown 

in a SHOW PROCESS display). 

PROCESS_PID The display-name suffix is the VMS process 

identification number (PID). 

If you specify /SUFFIX without a process-identifier-type keyword, the process 
identifier type used for the display-name suffix is, by default, the same as that 
used for the prompt suffix (see SET PROMPT/SUFFEX). 

/TOP 

Scrolls up to the top of the display’s text. 

/UP[:n] 

Scrolls up over the display’s text by n lines to reveal text further up in the 
display. If n is omitted, the display is scrolled by approximately 3/4 of its window 
height. 


Description 

The SCROLL command moves a display up, down, right, or left relative to its 
window so that various parts of the display text can be made visible through the 
window. 

Use the SELECT/SCROLL command to select the target display for the SCROLL 
command (the current scrolling display). 

See Appendix B for keypad-key definitions associated with the SCROLL 
command. 

Related command: SELECT. 


Examples 

1. DBG> SCROLL/LEFT 

This command scrolls the current scrolling display to the left by 8 columns. 

2. DBG> SCROLL/UP:4 ALPHA 

This command scrolls display ALPHA 4 lines up. 
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SEARCH 

Searches the source code for a specified string and displays source lines that 

contain an occurrence of the string. 

Format 

SEARCH [range] [string] 

Parameters 

range 

Specifies a program region to be searched. Use any of the following formats: 

mod-name Searches the specified module from line 0 to the 

end of the module. 

mod-name\line-num Searches the specified module from the specified 

line number to the end of the module. 

mod-name\line-num:line-num Searches the specified module from the line 

number specified on the left of the colon to the 
line number specified on the right. 

line-num Uses the current scope to find a module and 

searches that module from the specified line 
number to the end of the module. The current 
scope is that established by a previous SET 
SCOPE command, or the PC scope if no SET 
SCOPE command was entered. If you specify 
a scope search list with the SET SCOPE 
command, the debugger searches only the 
module associated with the first named scope. 

line-num:line-num Uses the current scope to find a module and 

searches that module from the line number 
specified on the left of the colon to the line 
number specified on the right. The current 
scope is that established by a previous SET 
SCOPE command, or the PC scope if no SET 
SCOPE command was entered. If you specify 
a scope search list with the SET SCOPE 
command, the debugger searches only the 
module associated with the first named scope. 

n ull (no entry) Searches the same module as that from which 

a source line was most recently displayed (as 
a result of a TYPE, EXAMINE/SOURCE, or 
SEARCH command, for example), beginning at 
the first line following the line most recently 
displayed and continuing to the end of the 
module. 


Specifies the source code characters for which to search. If you do not specify a 
string, the string specified in the last SEARCH command, if any, is used. 
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Qualifiers 


foUoXg condSont 6 ^ " qU ° tati ° n ( " > ° r a P° stro P hes under the 

The string has any leading or ending space or tab characters 
The string contains an embedded semicolon 
• The range parameter is null 

marks 1 “ marka > use two consecutive quotation 

marks ( ) to indicate an enclosed quotation mark. If the string is enclosed 

apostrophe heS> ^ tW ° COnsecutive a P°strophes (") to indicate an enclosed 


/ALL 

ff n e ^ fieS , that t . he debugger search for a U occurrences of the string in the specified 
range and display every line containing an occurrence of the string. 

/IDENTIFIER 

Specifies that the debugger search for an occurrence of the string in the specified 

thaf C H SP lf y c e St r ng ° nly ifit is not bounded on either side by a character 

that can be part of an identifier in the current language. 

/NEXT 

Specifies that the debugger search for the next occurrence of the string in the 
default range Snd dlSplay 0nly the line containing this occurrence. This is the 

/STRING 

iWrnS ^ at th ! d ! bUgger search for and dis P la y the string as specified, and not 
case of/IDENSS’STs ZdTfeT^ ’““ ^ ““ * d “ eS “ 


Description 


The SEARCH command displays the lines of source code that contain an 
occurrence of a specified string. 

3 m ° dala name ™ th the SEARCH command, that module must be 
t. lo determine whether a particular module is set, use the SHOW MODULE 
command, then use the SET MODULE command, if necessary. 

SEARCH command qualifiers determine whether the debugger: (1) searches 
^ r a °c cur rences (/ALL) of the string or only the next occurrence (/NEXT)- and 

IhltThf* ^ 0CCUr /f ce ° f ] he (/STRING) or only those occurrences in 

aiSnifi tnng 1S not bounded on either side by a character that can be part of 
an identifier in the current language (/IDENTIFIER). * 

If you plan to enter several SEARCH commands with the same qualifier you 
can first use the SET SEARCH command to establish a new default qualifier 

SEARCH/AT'n E ^ SEARC ? the SEARCH command behave like 

ARCH/ALL). Then you do not have to use that qualifier with the SEARCH 

° Ven ^ the CU f ent defau,t , ) uaIifiers { ° r duration of a 
single SEARCH command by specifying other qualifiers. 
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Examples 


Related commands: 

(SET,SHOW) LANGUAGE 
(SET,SHOW) MODULE 
(SET,SHOW) SCOPE 
(SET,SHOW) SEARCH 


1. DBG> SEARCH/STRING/ALL 40:50 D 
module COBOLTEST 


2 . 


40: 

02 

D2N 

41: 

02 

D 

42: 

02 

DN 

47: 

02 

DR0 

48: 

02 

DR5 

49: 

* 02 

DR10 

50: 

02 

DR15 


COMP-2 VALUE -234560000000. 
COMP-2 VALUE 222222.33. 
COMP-2 VALUE -222222.333333. 
COMP-2 VALUE 0.1 


COMP-2 VALUE 
COMP-2 VALUE 
COMP-2 VALUE 


0.000001. 

0.00000000001. 

0.0000000000000001. 


DBG> 

This command searches for all occurrences of the letter D in lines 40 to 50 of 
the module COBOLTEST, the module that is in the current scope. 

DBG> SEARCH/IDENTIFIER/ALL 40:50 D 
module COBOLTEST 

4 ^. 02 D COMP-2 VALUE 222222.33. 

DBG> 

This command searches for all occurrences of the letter D in lines 40 to 50 
of the module COBOLTEST. The debugger displays the only line where the 
letter D (the search string) is not bounded on either side by a character that 
can be part of an identifier in the current language. 

DBG> SEARCH/NEXT 40:50 D 

module; C OBOL T EST^ 2 ^ CO mp-2 VALUE -234560000000. 

DBG> 

This command searches for the next occurrence of the letter D in lines 40 to 
50 of the module COBOLTEST. 


4. 


COMP-2 VALUE 222222.33. 


DBG> SEARCH/NEXT 
module COBOLTEST 
41: 02 D 

DBG> 

This command searches for the next occurrence of the letter D. The debugger 
assumes D to be the search string because D was the last one entered and no 
other search string was specified. 


5. 


DBG> SEARCH 43 D 
module COBOLTEST 
47: 02 DR0 

DBG> 


COMP-2 VALUE 0.1. 


This command searches for the next occurrence (by default) of the letter D, 
starting with line 43. 
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nmw 3 SCT n en diSPlay SS the CU1Tent err0r ’ input > ins truction, output, program, 
prompt, scrolling, or source display. H ® 


Format 


SELECT [display-name] 


Parameters 


Qualifiers 


display-name 

dls Piny to be selected. You can specify any one of the following, with 
the restrictions noted in the qualifier descriptions: 

• A predefined display (SRC, OUT, INST, REG, and PROMPT) 

A display previously created with the DISPLAY command 

• A display built-in symbol: 

%CURDISP 

%CURSCROLL 

%NEXTDISP 

%NEXTINST 

%NEXTOUTPUT 

%NEXTSCROLL 

%NEXTSOURCE 

currprif >mit ir iS parai " et ® r aad do not s P eci fy a qualifier, you "unselect" the 
current scrolling display (no display then has the scrolling attribute). If you 

omit this parameter but specify a qualifier (/INPUT, /SOURCE, and so on) you 
unselect the current display with that attribute (see the qualifier descriptions). 

/ERROR 

If you specify a display, selects it as the current error display This causes all 

efthef? r ! gn ?1 iC r SSage u S t0 g ° t0 that displa * The dismay specified must be 
either an output display or the PROMPT display. 

e^r SPeCify 3 diSP ' ay ’ ^ PR0MPT < “ SPlay “ SCleCted SS ae mrrent 

By default, the PROMPT display has the error attribute. 

/INPUT 

If you specify a display, selects it as the current input display. This causes that 

ThP H 7 *1° eCh ° de fi bU / ger input (which alwa ys appears in the PROMPT display) 

The display specified must be an output display. 

If you do not specify a display, the current input display is unselected and 
PROMPT display) n0t diSplay (debu ^ er input appears only in the 

By default, no display has the input attribute. 
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If N you R S pedfy a display, selects it as the current instruction display. This 
causes the output of all EXAMINE/INSTRUCTION commands to go to that 
display. The display specified must be an instruction display. 

If you do not specify a display, the current instruction display is unselected and 
no display has the instruction attribute. 

Bv default for all languages except MACRO, no display has the instruction 
tribute if the language is set to MACRO, the INST display has the instruct,® 
attribute by default. 

If yoiT specify a display, selects it as the current output display. This causes 
debugger output that is not already directed to another display to go * 
display. The display specified must be either an output display or the PROMPT 

display. 

If you do not specify a display, the PROMPT display is selected as the current 
output display. 

By default, the OUT display has the output attribute. 

If vmfspedfy a display, selects it as the current program display This causes 
the debugger to try to force program input and output to that display. Curren y, 
only the PROMPT display can be specified. 

If you do not specify a display, the current program display is ^selected and 
program input and output are no longer forced to the specified display. 

By default, the PROMPT display has the program attribute, except on 
workstations, where the program attribute is unselected. 

Selects^the specified display as the current prompt display. This is where 
the debugger prompts for input. Currently, only the PROMPT display can be 
specified. Moreover, you cannot unselect the PROMPT display (the PROMPT 
display always has the prompt attribute). 

If you specify a display, selects it as the current scrolling display. Th 18 ^ the 

default display for the SCROLL, MOVE, and EXPAND a " d KCPAND 

display can have the scroll attribute, you can use oniy the MOVE and EXPAND 
commands (not the SCROLL command) with the PROMPT display. 

If you do not specify a display, the current scrolling display is unselected and no 
display has the scroll attribute. 

Bv default for all languages except MACRO, the SRC display has the scroll 
Attribute ! if 1^he langu^is set to MACRO, the INST display has the scroll 

attribute by default. 

If no qualifier is specified, /SCROLL is assumed by default. 

If voiTScify a display, selects it as the current source display. This causes 
the output of all TYPE and EXAMINE/SOURCE commands to go to that display. 
The display specified must be a source display. 
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If you do not specify a display, the current source display is unselected and no 
display has the source attribute. unseiected and no 

languages except MACRO, the SRC display has the source 
by defeat “ lgUa8e 18 Se ‘ *° MACR0> di8play has source attribute 


/SUFFIX[=process-identifier-type] 

value'MULTIPROO^?, 8 eouflguration (when DBGJPROCESS has the 

value MULTIPROCESS). Use this qualifier only directly after a display name. 

Appends a process-identifying suffix to a display name. The suffix denotes the 
visible process at the time the command was issued. This qualifier is used 

dS^tions th C a °t mma h d P ™f d ” re ® When s ? ecif ying display definitions or key 
definitions that are bound to display definitions. 

Use any of the following process-identifier-type keywords: 

PROCESS_NAME The display-name suffix is the VMS process name. 

ROCESS.NUMBER The display-name suffix is the process number (as shown 

m a SHOW PROCESS display). 

PROCESS.PID The display-name suffix is the VMS process 

identification number (PID). 

tf you specify /SUFFIX without & process-identifier-type keyword, the process 

used^fo 6 ^ 6 USed /° r i he dis P lay - name suffix is, by default, the same as that 
used for the prompt suffix (see SET PROMPT/SUFFIX). 


Description 


^ US6d \° SdeCt thG CU1Tent scrolIin § display and to direct various 
Sn. Tf 1- °?£ Ut t0 particular displays. This gives you the option of 
lxing or isolating different types of information, such as debugger input output 
diagnostic messages, and so on in scrollable displays. ’ ’ 

You use the SELECT command with one or more qualifiers (/ERROR, /SOURCE 
and so on) to assign one or more corresponding attributes to a display. If you do’ 
not specify a qualifier, the /SCROLL qualifier is assumed by default. 

the 'Ztrih f 6 SELECT command without specifying a display name, in general 
the attribute assignment indicated by the qualifier is canceled (unselected) lb 
reassign display attributes you must use another SELECT command. See the 
individual qualifier descriptions for details. 

See Appendix B for keypad-key definitions associated with the SELECT 
command. 

Related commands: 


DISPLAY 
EXPAND 
MOVE 
SCROLL 
SHOW SELECT 
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Examples 


DBG> SELECT/SOURCE/SCROLL SRC2 

This command selects display SRC2 as the current source and scrolling 
display. 

DBG> SELECT/INPUT/ERROR OUT 

This command selects display OUT as the current input «ad «mr display 

This causes debugger input, debugger output (assuming 

output display), and debugger diagnostic messages to be logged in the OU1 

display in the correct sequence. 

DBG> SELECT/SOURCE 

This command unselects (deletes the sourceLf‘ trib ^/r?T> 
selected source display. The output ot a TYPE or EXdMINE/SOURCE 
command then goes to the currently selected output display. 
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Assigns the debugger’s abort function to another Ctrl-key 
Ctrl/C does the abort function. 


sequence. By default, 


Format 

SET ABORT_KEY = CTRL_character 

Parameters 


character 

flpSta* haSn PrcSS WhUe h ° lding d<Wn ‘ he CW tey Y °“ ““ ^ “V 


Description 


the eiecutio^of !a h sequence ’ whe * entered within a debugging session, aborts 
SET Sort ^v bUgge 7° m T 1 and and interru P ts program execution. The 
rfrl.w° RT-KEY m^ mand enables y° u to assign the abort function to another 
• y se ^ uence - This might be necessary if your program has a Ctrl/C AST 
service routine enabled. 

ctrl - ke y sequences have VMS predefined functions, and the SET ABORT 
Y command enables you to override such definitions (see the VMS DCL 

TkTJS t key chiracters not used by 1116 VMS 

al'ctTIl°5 T ftS„ COmmand iden “ es the Ctrl - key -»-* - 

?r° fl n°i USe C , trL 7 r J‘^ Within 3 debu ssi n & session. Always use either Ctrl/C 
or an equivalent Ctrl-key sequence established with the SET ABORT KEY 
command. - 


Related commands: 

Ctrl/C 

Ctrl/Y 

SHOW ABORT.KEY 


Example 


DBG> SHOW ABORT_KEY 
Abort Command Key is CTRL C 
DBG> GO 


Icwci 

DBG> <EriNE/BYTE 1000:101000 Ishould have typed 1000:1010 

1004: 0 
1008: 0 
1012: 0 
1016: 0 
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%DEBUG-W-ABORTED, command aborted by user request 
DBG> SET ABORT_KEY = CTRL_P 
DBG> GO 


DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010 

1000: 0 
1004: 0 
1008: 0 
1012: 0 
1016: 0 

%DEBUG-W-ABORTED , command aborted by user request 
DBG> 

This sequence of commands shows the following entities: 

. Use of the (default) Ctrl/C sequence to perform the abort function. 

• Use of the SET ABORT_KEY command to reassign the abort function to the 
Ctrl/P sequence. 
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SET ATSIGN 


Establishes the default file specification that the debugger uses when searching 
for command procedures. & 

Format 

SET ATSIGN file-spec 


Parameters 


Example 


file-spec 

Specifies any part of a VMS file specification (for example, a directory name or a 
file type) that the debugger is to use by default when searching for a command 

SvXm?* nZrt n l? P l a ful1 file ^deification, the debugger assumes 
SYS$DISK:[ JDEBUG.COM as the default file specification for any missing field. 

You can specify a logical name that translates to a search list. In this case, the 
ebugger processes the file specifications in the order they appear in the search 
list until the command procedure is found. 


Description 


When you invoke a command procedure during a debugging session, the debugger, 

OTT*™rn aSSUmeS that lts file specification is SYS$DISK:[ JDEBUG.COM The 
bET ATSIGN command enables you to override this default. 

Related commands: 

@ (Execute Procedure) 

SHOW ATSIGN 


DBG> set ATSIGN USER:[JONES.DEBUG].DBG 
DBG> 0TEST 

In this example, when the user invokes 
TEST.DBG in USER:[JONES.DEBUG], 


@TEST, the debugger looks for the file 
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SET BREAK 


Format 


Parameters 


Establishes a breakpoint at the location denoted by an address expression, at 
instructions of a particular class, or at the occurrence of specified events. 


SET BREAK [address-expression[, ... ]] [WHEN(conditional-expression)] 
[DO(command[; ...])] 


address-expression . 

Specifies an address expression (a program location) at which a breakpoint is 
to be set. With high-level languages, this is typically a line number, a routin 
name, or a label, and can include a pathname to specify the entity uniquely \ 
More generally, an address expression can also be a memory address or a regi 
and can be composed of numbers (offsets) and symbols, as well as one or more 
operators, operands, or delimiters. Appendix D identifies the operators that can 
be used in address expressions. 


Do not specify the asterisk (*) wildcard character. Do not specify an address 
expression with any of the following qualifiers. 


/ACTIVATING 

/BRANCH 

/CALL 

/EXCEPTION 

/INSTRUCTION[=(opco<2e . . . )] 


/INTO 

/[NO]JSB 

/LINE 

/OVER 

/[NOISHARE 

/[NOjSYSTEM 

/TERMINATING 

/VECTORJNSTRUCTION 

The /MODIFY and /RETURN qualifiers are used with specific kinds of address 


expressions. 

If you specify a memory address or an address expression whose value is not 
a symbolic location, check (with the EXAMINE command) that an instruction 
actually begins at the byte of memory so indicated. If an instruction ^°® s 
begin at this byte, a run-time error can occur when an instruction includi g 
byS is executed. When you set a breakpoint by specifying an address expression 
whose value is not a symbolic location, the debugger does not vei^ thatt 
location specified marks the beginning of an instruction. CALLS and CALLG 
routines start with an entry mask. 


conditional-expression ,, , . , , 

Specifies a conditional expression in the currently set language that is to be 
evaluated when execution reaches the breakpoint. If the expression is true, 
break action occurs, and the debugger reports that a break has occurred, 
expression is false, break action does not occur. In this case, a report is not 
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issued, the commands specified by the DO clause are not executed, and program 
execution is continued. 

command 

Specifies a debugger command to be executed as part of the DO clause when 
break action is taken. 

Qualifiers 

/ACTIVATING 

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 

Causes the debugger to break when a new process comes under debugger control. 
The debugger prompt is displayed when the first process comes under debugger 
control. This enables you to enter debugger commands before the program has 
started execution. Do not specify an address expression with /ACTIVATING. See 
also /TERMINATING. 

/AFTERin 

Specifies that break action not be taken until the rath time the designated 
breakpoint is encountered (ra is a decimal integer). Thereafter, the breakpoint 
occurs every time it is encountered provided that conditions in the WHEN clause 
(if specified) are true. The SET BREAK/AFTER: 1 command has the same effect 
as the SET BREAK command. 

/BRANCH 

Causes the debugger to break on every branch instruction encountered during 
program execution. Do not specify an address expression with /BRANCH. See 
also /INTO and /OVER. 

/CALL 

Causes the debugger to break on every call instruction encountered during 
program execution, including the RET instruction. Do not specify an address 
expression with /CALL. See also /INTO and /OVER. 

/EVENT=event-name 

Causes the debugger to break on the specified event (if that event is defined and 
detected by the current event facility). If you specify an address expression with 
/EVENT, causes the debugger to break whenever the specified event occurs for 
that address expression. You cannot specify an address expression with certain 
event names. 

Event facilities are available for programs that call Ada or SCAN routines or 
that use DECthreads services. Use the SHOW EVENT.FACILITY command to 
identify the current event facility and the associated event names. 

/EXCEPTION 

Causes the debugger to break whenever an exception is signaled. The break 
action occurs before any application-declared exception handlers are invoked. Do 
not specify an address expression with /EXCEPTION. 

As a result of a SET BREAK/EXCEPTION command, whenever your program 
generates an exception, the debugger suspends program execution, reports 
the exception, and displays its prompt. When you resume execution from an 
exception breakpoint, the behavior is as follows: 
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• If you enter a GO command without an address-expression parameter, the 
exception is resignaled, thus allowing any application-declared exception 
handler to execute. 

• If you enter a GO command with an address-expression parameter, program 
execution continues at the specified location, thus inhibiting the execution of 
any application-declared exception handler. 

• If you enter a STEP command, the debugger steps into any application- 
declared exception handler. If there is no application-declared handler for 
that exception, the debugger resignals the exception. 

• If you enter a CALL command, the routine specified is executed. If a routine 
is called with the CALL command directly after an exception breakpoint has 
been triggered, no breakpoints, tracepoints, or watchpoints set within that 
routine are triggered. However, they are triggered if the CALL command is 
given at another time. 

/INSTRUCTION[=(opcode[, ...])] 

If you do not specify an opcode, causes the debugger to break on every instruction 
encountered during program execution. If you specify one or more opcodes, causes 
the debugger to break on every instruction whose opcode is in the list. 

Do not specify an address expression with this qualifier. If you specify a vector 
instruction, do not include an instruction qualifier (/U, /V, /M, 10, or /l) with the 
instruction mnemonic. See also /INTO and /OVER. 

/INTO 

Applies only to breakpoints set with the following qualifiers—that is, when an 
address expression is not explicitly specified: 

/BRANCH 

/CALL 

/INSTRUCTION[=(qpcode . . . )] 

/LINE 

/VECTORJNSTRUCTION 

When used with those qualifiers, causes the debugger to break at the specified 
points within called routines (as well as within the routine in which execution 
is currently suspended). The /INTO qualifier is the default behavior and is the 
opposite of /OVER. 

When using /INTO, you can further qualify the break action with the /[NO]JSB, 
/[NOJSHARE, and /[NOJSYSTEM qualifiers. 

/JSB 

/NOJSB 

Qualifies /INTO. Use /[NO]JSB only with /INTO and one of the following 
qualifiers: 

/BRANCH 

/CALL 

/INSTRUCTION[=(opcocfe ... )] 

/LINE 

/VECTORJNSTRUCTION 
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The /JSB qualifier is the default for all languages except DIBOL. The /JSB 
qualifier permits the debugger to break within routines that are called by the 
JSB or CALL instruction. The /NOJSB qualifier (the DIBOL default) specifies 
that breakpoints not be set within routines called by JSB instructions. In DIBOL, 
application-declared routines are called by the CALL instruction and DIBOL 
run-time library routines are called by the JSB instruction. Do not specify an 
address expression with /[NOJJSB. 

/LINE 

Causes the debugger to break on the beginning of each source line encountered 
during program execution. Do not specify an address expression with /LINE. See 
also /INTO and /OVER. 

/MODIFY 

Causes the debugger to break on every instruction that writes to and modifies the 
value of the location indicated by the address expression. The address expression 
is typically a variable name. 

The SET BREAK/MODIFY command acts exactly like a SET WATCH command 
and operates under the same restrictions. 

If you specify an absolute address for the address expression, the debugger might 
not be able to associate the address with a particular data object. In this case, the 
debugger uses a default length of 4 bytes. You can change this length, however, 
by setting the type to either WORD (SET TYPE WORD, which changes the 
default length to 2 bytes) or BYTE (SET TYPE BYTE, which changes the default 
length to 1 byte). SET TYPE LONGWORD restores the default length of 4 bytes. 

/OVER 

Applies only to breakpoints set with the following qualifiers—that is, when an 
address expression is not explicitly specified: 

/BRANCH 

/CALL, 

/INSTRUCTION[=(opcode . . . )] 

/LINE 

/VECTORJNSTRUCTION 

When used with those qualifiers, causes the debugger to break at the specified 
points only within the routine in which execution is currently suspended (not 
within called routines). The /OVER qualifier is the opposite of /INTO (the default 
behavior). 

/RETURN 

Causes the debugger to break on the RET (return) instruction of the routine 
associated with the specified address expression (which can be a routine name, 
line number, and so on). This qualifier can only be applied to routines called 
with a CALLS or CALLG instruction; it cannot be used with JSB routines. 
Breaking on the RET instruction enables you to inspect the local environment (for 
example, obtain the values of local variables) before the RET instruction deletes 
the routine’s call frame from the call stack. 

For this qualifier, the address-expression parameter is an instruction address 
within a CALLS or CALLG routine. It can simply be a routine name, in which 
case it specifies the routine start address. However, you can also specify another 
location in a routine, so you can see only those returns that are taken after a 
certain code path is followed. 
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A SET BREAK/RETURN command cancels a previous SET BREAK command if 
the same address expression is specified. 

/SHARE (default) 

/NOSHARE 

Qualifies /INTO. Use /[NO]SHARE only with /INTO and one of the following 
qualifiers: 

/BRANCH 

/CALL 

/INSTRUCTION[=(opcocte . . . )] 

/LINE 

/VECTOR.INSTRUCTION 

The /SHARE qualifier permits the debugger to break within shareable image 
routines as well as other routines. The /NOSHARE qualifier specifies that 
breakpoints not be set within shareable images. Do not specify an address 
expression with /[NOJSHARE. 

/SILENT 

/NOSILENT (default) 

Controls whether the "break ..." message and the source line for the current 
location are displayed at the breakpoint. The /NOSILENT qualifier specifies that 
the message is displayed. The /SILENT qualifier specifies that the message and 
the source line are not displayed. The /SILENT qualifier overrides /SOURCE. See 
also SET STEP [NO]SOURCE. 

/SOURCE (default) 

/NOSOURCE 

Controls whether the source line for the current location is displayed at the 
breakpoint. The /SOURCE qualifier specifies that the source line is displayed. 
The /NOSOURCE qualifier specifies that no source line is displayed. The 
/SILENT qualifier overrides /SOURCE. See also SET STEP [NO]SOURCE. 

/SYSTEM (default) 

/NOSYSTEM 

Qualifies /INTO. Use /[NOJSYSTEM only with /INTO and one of the following 
qualifiers: 

/BRANCH 

/CALL 

/INSTRUCTION[=(opcode . . . )] 

/LINE 

/VECTOR.INSTRUCTION 

The /SYSTEM qualifier permits the debugger to break within system routines 
(PI space) as well as other routines. The /NOSYSTEM qualifier specifies that 
breakpoints not be set within system routines. Do not specify an address 
expression with /[NOJSYSTEM. 

/TEMPORARY 

Causes the breakpoint to disappear after it is triggered (the breakpoint does not 
remain permanently set). 
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/TERMINATING 

Causes the debugger to break when a process does an image exit. The debugger 
always gains control and displays its prompt when the last image of a one-process 
or multiprocess program exits. A process is terminated when the image has 
executed the $EXIT system service and all of its exit handlers have executed. Do 
not specify an address expression with /TERMINATING. See also /ACTIVATING. 

A/ECTOR.INSTRUCTION 

Causes the debugger to break on every vector instruction encountered during 
program execution. Do not specify an address expression with /VECTOR_ 
INSTRUCTION. See also /INTO and /OVER. 

Description 

When a breakpoint is triggered, the debugger takes the following action: 

1. Suspends program execution at the breakpoint location. 

2. If /AFTER was specified when the breakpoint was set, checks the AFTER 
count. If the specified number of counts has not been reached, execution is 
resumed and the debugger does not perform the remaining steps. 

3. Evaluates the expression in a WHEN clause, if one was specified when 
the breakpoint was set. If the value of the expression is false, execution is 
resumed and the debugger does not perform the remaining steps. 

4. Reports that execution has reached the breakpoint location by issuing a 
"break ..." message, unless /SILENT was specified. 

5. Displays the line of source code at which execution is suspended, unless 
/NOSOURCE or /SILENT was specified when the breakpoint was set, or SET 
STEP NOSOURCE was entered previously. 

6. Executes the commands in a DO clause, if one was specified when the 
breakpoint was set. If the DO clause contains a GO command, execution 
continues and the debugger does not perform the next step. 

7. Issues the prompt. 

You set a breakpoint at a particular location in your program by specifying an 
address expression with the SET BREAK command. You set a breakpoint on 
consecutive source lines, classes of instructions, or events by specifying a qualifier 
with the SET BREAK command. Generally, you must specify either an address 
expression or a qualifier, but not both. Exceptions are the /EVENT and /RETURN 
qualifiers. 

The /LINE qualifier sets a breakpoint on each line of source code. 

The following qualifiers set breakpoints on classes of instructions. Use of 
these qualifiers and of the /LINE qualifier causes the debugger to trace every 
instruction of your program as it executes and thus significantly slows down 
execution: 

/BRANCH 

/CALL 

/INSTRUCTION[=(qpcocfe[, ...])] 

/RETURN 

/VECTORJNSTRUCTION 
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The following qualifiers set breakpoints on classes of events: 

/ACTIVATING 

/EVENT=event-name 

/EXCEPTION 

/TERMINATING 

The following qualifiers affect what happens at a routine call: 

/INTO 

/[NO]JSB 

/OVER 

/[NOJSHARE 

/[NOJSYSTEM 

The following qualifiers affect what output is displayed when a breakpoint is 
reached: 

/[NOJSILENT 

/[NOJSOURCE 

The following qualifiers affect the timing and duration of breakpoints: 

/AFTER:n 

/TEMPORARY 

The /MODIFY qualifier is used to monitor changes at program locations (typically 
changes in the values of variables). 

If you set a breakpoint at a location currently used as a tracepoint, the tracepoint 
is canceled in favor of the breakpoint, and vice versa. 

Breakpoints can be user defined or predefined. User defined breakpoints are 
those that you set explicitly with the SET BREAK command. Predefined 
breakpoints, which depend on the type of program you are debugging (for 
example, Ada or multiprocess), are established automatically when you invoke 
the debugger. Use the SHOW BREAK command to identify all breakpoints that 
are currently set. Any predefined breakpoints are identified as such. 

User defined and predefined breakpoints are set and canceled independently. 

For example, a location or event can have both a user defined and a predefined 
breakpoint. Canceling the user defined breakpoint does not affect the predefined 
breakpoint, and conversely. 

Related commands: 

CANCEL ALL 
GO 

(SET,SHOW) EVENT.FACILITY 
SET STEP [NOJSOURCE 
SET TRACE 
SET WATCH 

(SHOW,CANCEL) BREAK 
STEP 
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Examples 

1. DBG> SET BREAK SWAP\%LINE 12 

This command causes the debugger to break on line 12 of module SWAP. 

2. DBG> SET BREAK/AFTER:3 SUB2 

This command causes the debugger to break on the third and subsequent 
times that SUB2 (a routine) is executed. 

3. DBG> SET BREAK/NOSOURCE L00P1 DO (EXAMINE D; STEP; EXAMINE Y; GO) 

This command causes the debugger to break at location LOOP1. At the 
breakpoint, the following commands are issued, in the order given: EXAMINE 
D, STEP, EXAMINE Y, and GO. The /NOSOURCE qualifier suppresses the 
display of source code at the breakpoint. 

4. DBG> SET BREAK R0UT3 WHEN (X > 4) DO (EXAMINE Y) 

This command causes the debugger to break on routine ROUT3 when 
X is greater than 4. At the breakpoint, the EXAMINE Y command is 
issued. The syntax of the conditional expression in the WHEN clause is 
language-dependent. 

5. DBG> SET BREAK/TEMPORARY 1440 
DBG> SHOW BREAK 
breakpoint at 1440 [temporary] 

DBG> 

This command sets a temporary breakpoint at memory address 1440. After 
that breakpoint is triggered, it disappears. 

6. DBG> SET BREAK/LINE 

This command causes the debugger to break on the beginning of every source 
fine encountered during program execution. 

7. DBG> SET BREAK/LINE WHEN (X .NE. 0) 

DBG> SET BREAK/INSTRUCTION WHEN (X .NE. 0) 

These two commands cause the debugger to break when X is not equal to 0. 
The first command tests for the condition at the beginning of every source line 
encountered during execution. The second command tests for the condition 
at each instruction. The syntax of the conditional expression in the WHEN 
clause is language-dependent. 

8. DBG> SET BREAK/INSTRUCTION=ADDL3 

This command causes the debugger to break whenever the instruction ADDL3 
is about to be executed. 

9. DBG> SET BREAK/LINE/INTO/NOSHARE/NOSYSTEM 

This command causes the debugger to break on the beginning of every source 
line, including lines in called routines (/INTO) but not in shareable image 
routines (/NOSHARE) or system routines (/NOSYSTEM). 
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10. DBG> SET BREAK/RETURN R0UT4 

This command causes the debugger to break whenever the RET instruction of 
routine ROUT4 is about to be executed. 

11. DBG> SET BREAK/RETURN %LINE 14 

This command causes the debugger to break whenever the RET instruction 
of the routine that includes line 14 is about to be executed. This form of the 
command is useful if execution is currently suspended within a routine and 
you want to set a breakpoint on that routine’s RET instruction. 

12. DBG> SET BREAK/EXCEPTION DO (SET MODULE/CALLS; SHOW CALLS) 

This command causes the debugger to break whenever an exception is 
signaled. At the breakpoint, the SET MODULE/CALLS and SHOW CALLS 
commands are issued. 

13. DBG> SET BREAK/EVENT=RUN RESERVE, %TASK 3 

This command sets two breakpoints, which are associated with task 
RESERVE and task 3 (task ID = 3), respectively. Each breakpoint is triggered 
whenever its associated task makes a transition to the RUN state. 

14. DBG_1> SET BREAK/ACTIVATING 

This command causes the debugger to break whenever a process of a 
multiprocess program is brought under debugger control. 
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SET DEFINE 

Establishes a default qualifier (/ADDRESS, /COMMAND, /PROCESS_GROUP, or 
/VALUE) for the DEFINE command. 

Format 

SET DEFINE define-default 

Parameters 

define-default 

Specifies the default to be established for the DEFINE command. Valid keywords 
(which correspond to DEFINE command qualifiers) are as follows: 

ADDRESS Subsequent DEFINE commands are treated as 

DEFINE/ADDRESS. This is the default. 

COMMAND Subsequent DEFINE commands are treated as 

DEFINE/COMMAND. 

PROCESS_GROUP Subsequent DEFINE commands are treated as 

DEFINE/PROCESS_GROUP. 

VALUE Subsequent DEFINE commands are treated as 

DEFINE/VALUE. 

Description 

The SET DEFINE command establishes a default qualifier for subsequent 
DEFINE commands. The parameters that you specify in the SET DEFINE 
command have the same names as the DEFINE command qualifiers. The 
qualifiers determine whether the DEFINE command binds a symbol to an 
address, a command string, a list of processes, or a value. 

You can override the current DEFINE default for the duration of a single 
DEFINE command by specifying another qualifier. Use the SHOW DEFINE 
command to identify the current DEFINE defaults. 

Related commands: 

DEFINE 

DEFINE/PROCESS_GROUP 

DELETE 

SHOW DEFINE 

SHOW SYMBOL/DEFINED 

Example 

DBG> SET DEFINE VALUE 

The SET DEFINE VALUE command specifies that subsequent DEFINE 
commands are treated as DEFINE/VALUE. 
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SET EDITOR 


Establishes the editor that is invoked by the EDIT command. 

Format 

SET EDITOR [command-line] 

Parameters 

command-line 

Specifies a command line to invoke a particular editor on your system when you 
use the EDIT command. 

You must specify a command line unless you use the /CALLABLE_EDT, 
/CALLABLE_LSEDIT, or /CALLABLE_TPU qualifiers. If you do not use one 
of these qualifiers, the editor specified in the SET EDITOR command line is 
spawned to a subprocess when you enter the EDIT command. 

You can specify a command line with the /CALLABLE_LSEDIT and /CALLABLE_ 
TPU qualifiers, but not with the /CALLABLE_EDT qualifier. 

Qualifiers 

/CALLABLE_EDT 

Specifies that the callable version of the EDT editor is invoked when you use 
the EDIT command. Do not specify a command line with /CALLABLE_EDT (a 
command line of "EDT" is used). 

/CALLABLE_LSEDIT 

Specifies that the callable version of the VAX Language-Sensitive Editor 
(LSEDIT) is invoked when you use the EDIT command. If you also specify a 
command line, it is passed to callable LSEDIT. If you do not specify a command 
line, the default command line is "LSEDIT". 

/CALLABLE_TPU 

Specifies that the callable version of the VAX Text Processing Utility (VAXTPU) is 
invoked when you use the EDIT command. If you also specify a command line, it 
is passed to callable VAXTPU. If you do not specify a command line, the default 
command line is "TPU". 

/START_POSITION 
/NOSTART_POSITION (default) 

Currently, only VAXTPU and the VAX Language-Sensitive Editor (specified either 
as TPU or /CALLABLE.TPU, and LSEDIT or /CALLABLE_LSEDIT, respectively) 
support /START_POSITION. 

Controls whether the /START_POSITION qualifier is appended to the specified 
or default command line when the EDIT command is used. This qualifier affects 
the initial position of the editor’s cursor. By default, (/NOSTART_POSITION), the 
editor’s cursor is placed at the beginning of source line 1, regardless of which line 
is centered in the debugger’s source display or whether a line number is specified 
in the EDIT command. If /START_POSITION is specified, the cursor is placed 
either on the line whose number is specified in the EDIT command, or (if no line 
number is specified) on the line that is centered in the current source display. 


CD-134 




Debugger Command Dictionary 
SET EDITOR 


Description 

The SET EDITOR command enables you to specify any editor that is installed 
on your system. In general, the command line specified as parameter to the SET 
EDITOR command is spawned and executed in a subprocess. However, if you 
use EDT, LSEDIT, or VAXTPU, you have the option of invoking these editors 
in a more efficient way. You can specify the /CALLABLE_EDT, /CALLABLE. 
LSEDIT, or /CALLABLE.TPU qualifiers, which cause the callable versions of 
EDT, LSEDIT, and VAXTPU, respectively, to be invoked by the EDIT command. 
In the case of LSEDIT and VAXTPU, you can also specify a command line that is 
executed by the callable editor. 

Related commands: 

EDIT 

(SET,SHOW,CANCEL) SOURCE 
SHOW DEFINE 

Examples 

1. DBG> SET EDITOR ' @MAIL$EDIT 

This command causes the EDIT command to spawn the command line 
’@MAIL$EDIT which invokes the same editor as you use in MAIL. 

2. DBG> SET EDITOR/CALLABLE_TPU 

This command causes the EDIT command to invoke callable VAXTPU with 
the default command line of TPU. 

3. DBG> SET EDITOR/CALLABLE_TPU TPU/SECTION=MYSECINI.TPU$SECTION 

This command causes the EDIT command to invoke callable VAXTPU with 
the command line TPU/SECTION=MYSECINI.TPU$SECTION. 

4. DBG> SET EDITOR/CALLABLE_LSEDIT/START_POSITION 

This command causes the EDIT command to invoke callable LSEDIT with 
the default command line of LSEDIT. Also the /START.POSITION qualifier 
is appended to the command line, so that the editing session starts on the 
source line that is centered in the debugger’s current source display. 
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SET EVENT_FACILITY 

Establishes the current event facility. 

Event facilities are available for programs that call Ada or SCAN routines or that 
use DECthreads services. 

Format 

SET EVENT_FACILITY facility-name 


Parameters 

facility-name 

Specifies an event facility. Valid facility-name keywords are as follows: 

ADA If the event facility is set to ADA, the (SET,CANCEL) BREAK and 

(SET,CANCEL) TRACE commands recognize Ada-specific events as 
well as generic, low-level task events. (Ada events consist of task 
and exception events.) 

You can set the event facility to ADA only if the main program is 
written in Ada or if the program calls an Ada routine. 

THREADS If the event facility is set to THREADS, the (SET,CANCEL) BREAK 
and (SET,CANCEL) TRACE commands recognize DECthreads- 
specific as well as generic, low-level task events. All DECthreads 
events are task (thread) events. 

You can set the event facility to THREADS only if the shareable 
image CMA$RTL is currently part of the program’s process (if that 
image is listed in a SHOW IMAGE display). 

SCAN If the event facility is set to SCAN, the (SET,CANCEL) BREAK 
and (SET,CANCEL) TRACE commands recognize SCAN (pattern- 
matching) events. 

You can set the event facility to SCAN only if the main program is 
written in SCAN or if the program calls a SCAN routine. 

Description 

The current event facility (ADA, THREADS, or SCAN) defines the eventpoints 
that you can set with the SET BREAK/EVENT and SET TRACE/EVENT 
commands. 

When invoked with a program that is linked with an event facility, the debugger 
automatically sets the facility in a manner appropriate for the type of program. 
For example, if the main program is written in Ada or SCAN, the event facility is 
set to ADA or SCAN, respectively. 

The SET EVENT_FACILITY command enables you to change the event facility 
and thereby change your debugging context. This is useful if you have a 
multilanguage program and want to debug a routine that is associated with 
an event facility but that facility is not currently set. 
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—-- Note _ 

Currently you cannot use both Ada and DECthreads tasking services in 
the same program. This implies that you can change the event facility 
only from ADA to SCAN or from DECthreads to SCAN, or conversely. 


Use the SHOW EVENT_FACILITY command to identify the event names 
associated with the current event facility. These are the keywords that you can 
specify with the (SET,CANCEL) BREAK/EVENT and (SET,CANCEL) TRACE 
/EVENT commands. 

Related commands: 

(SET,CANCEL) BREAK/EVENT 

(SET,CANCEL) TRACE/EVENT 

SHOW BREAK 

SHOW EVENT_FACILITY 

SHOW IMAGE 

SHOW TASK 

SHOW TRACE 


Example 


DBG> SET EVENT_FACILITY THREADS 

This command establishes THREADS (DECthreads) as the current event facility. 
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SET IMAGE 

Loads symbol information for one or more shareable images and establishes the 
current image. 

Format 

SET IMAGE [image-name[, ... ]] 

Parameters 

image-name 

Specifies a shareable image to be "set." Do not use the asterisk (*) wildcard 
character. Instead, use the /ALL qualifier. Do not specify an image name with 
/ALL. 

Qualifiers 

/ALL 

Specifies that all shareable images are set. Do not specify an image with /ALL. 

Description 

The SET IMAGE command builds data structures for one or more specified 
images but does not set any modules within the images specified. 

The "current" image is the current debugging context: you have access to 
symbols in the current image. If only one image is specified with the SET IMAGE 
command, that image becomes the current image. If a list of images is specified, 
the last one in the list becomes the current image. If /ALL is specified, the 
current image is unchanged. 

Before an image can be set with the SET IMAGE command, it must have been 
linked with the /DEBUG or /TRACEBACK qualifier on the LINK command. If an 
image was linked /NOTRACEBACK, no symbol information is available for that 
image and you cannot specify it with the SET IMAGE command. 

Definitions created with the DEFINE/ADDRESS and DEFINE/VALUE commands 
are available only when the image in whose context they were created is the 
current image. When you use the SET IMAGE command to establish a new 
current image, these definitions are temporarily unavailable. Definitions created 
with the DEFINE/COMMAND and DEFINE/KEY commands are always available 
for all images, however. 

Related commands: 

SET MODE [NOIDYNAMIC 
(SET,SHOW,CANCEL) MODULE 
(SHOW,CANCEL) IMAGE 
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Example 


DBG> SET IMAGE SHARE1 
DBG> SET MODULE SUBR 
DBG> SET BREAK SUBR 

This sequence of commands shows how to set a breakpoint on routine SUBR in 
module SUBR of shareable image SHARE 1. The SET IMAGE command sets 
the debugging context to SHARE 1. The SET MODULE command loads the 
symbol records of module SUBR into the RST. The SET BREAK command sets a 
breakpoint on routine SUBR. 
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SET KEY 

Establishes the current key state. 

Format 

SET KEY 

Qualifiers 

/LOG (default) 

/NOLOG 

Controls whether a message is displayed indicating that the key state has been 
set. The /LOG qualifier displays the message. 

/STATE[=state-name] 

/NOSTATE (default) 

Specifies a key state to be established as the current state. You can specify a 
predefined key state, such as GOLD, or a user-defined state. A state name can be 
any appropriate alphanumeric string. The /NOSTATE qualifier leaves the current 
state unchanged. 

Description 

Keypad mode must be enabled (SET MODE KEYPAD) before you can use this 
command. Keypad mode is enabled by default. 

By default, the current key state is the "DEFAULT" state. When you define 
function keys using the DEFINE/KEY command, you can use the /IFJ3TATE 
qualifier of that command to assign a specific state name to the key definition. 

If that state is not set when you press the key, the definition is not processed. 
The SET KEY/STATE command enables you to change the current state to the 
appropriate state. 

You can also change the current state by pressing a key that causes a state 
change (a key that was defined with the DEFINE/KEY/LOCK_STATE/SET_ 
STATE qualifier combination). 

Related commands: 

DELETE/KEY 
DEFINE/KEY 
SHOW KEY 

Example 


DBG> SET KEY/STATE=PR0G3 

This command changes the key state to the PROG3 state. The user can now use 
the key definitions that are associated with this state. 
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SET LANGUAGE 


Establishes the current language. 

Format 

SET LANGUAGE language-name 


Parameters 


language-name 

Specifies a language. Valid keywords are ADA, BASIC, BLISS, C, COBOL, 
DIBOL, FORTRAN, MACRO, PASCAL, PLI, RPG, SCAN, and UNKNOWN. 

Description 

When you invoke the debugger with the RUN command, the debugger sets the 
current language to that in which the module containing the main program is 
written. This is usually the module containing the image transfer address. To 
debug a module written in a different source language from that of the main 
program, you can change the language with the SET LANGUAGE command. 

The current language setting determines how the debugger parses and interprets 
the names, operators, and expressions you specify in debugger commands, 
including things like the typing of variables, array and record syntax, the default 
radix for the entry and display of integer data, case sensitivity, and so on. The 
language setting also determines how the debugger formats and displays data 
associated with your program. 

The default radix for both data entry and display is decimal for all languages 
except BLISS and MACRO. It is hexadecimal for BLISS and MACRO. The default 
type for program locations that do not have a compiler generated type is longword 
integer. 

The SET LANGUAGE UNKNOWN command is used when debugging a program 
that is written in an unsupported language. To maximize the usability of the 
debugger with unsupported languages, the SET LANGUAGE UNKNOWN 
command causes the debugger to accept a large set of data formats and operators, 
including some that might be specific to only a few supported languages. 

The operators and constructs that are recognized for each SET LANGUAGE 
command parameter are identified in Appendix E. 

Related commands: 

EVALUATE 

EXAMINE 

DEPOSIT 

SET MODE 

SET RADIX 

SET TYPE 

SHOW LANGUAGE 
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Examples 

1. DBG> SET LANGUAGE COBOL 

This command establishes COBOL as the current language. 

2. DBG> SET LANGUAGE PASCAL 

T his command establishes Pascal as the current language. 
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SET LOG 


Specifies a log file to which the debugger writes after a SET OUTPUT LOG 
command has been entered. 


Format 

SET LOG file-spec 

Parameters 


file-spec 

Denotes the file specification of the log file. If you do not supply a full file 
specification, the debugger assumes SYS$DISK:[ JDEBUG.LOG as the default file 
specification for any missing field. 

If you specify a version number and that version of the file already exists, the 
debugger writes to the file specified, appending the log of the debugging session 
onto the end of that file. 


Description 

The SET LOG command only determines the name of a log file; it does not cause 
the debugger to create or write to the specified file. The SET OUTPUT LOG 
command accomplishes that. 

If you have entered a SET OUTPUT LOG command but no SET LOG command, 
the debugger writes to the file SYS$DISK:[ JDEBUG.LOG by default. 

If the debugger is writing to a log file and you specify another log file with the 
SET LOG command, the debugger closes the former file and begins writing to the 
file specified in the SET LOG command. 

Related commands: 

SET OUTPUT LOG 

SET OUTPUT SCREENLOG 

SHOW LOG 

Examples 

1. DBG> SET LOG CALC 
DBG> SET OUTPUT LOG 

In this example, the SET LOG command specifies the debugger log file to 
be SYS$DISK:[ JCALC.LOG. The SET OUTPUT LOG command causes user 
input and debugger output to be logged to that file. 

2. DBG> SET LOG " [CODEPROJ]FEB29.TMP" 

DBG> SET OUTPUT LOG 

In this example, the SET LOG command specifies the debugger log file to 
be [CODEPROJ]FEB29.TMP. The SET OUTPUT LOG command causes user 
input and debugger output to be logged to that file. 
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SET MARGINS 

Specifies the leftmost and rightmost source-line character position at which to 
begin and end display of a source line. 


Format 

SET MARGINS rm 

Irrv.rm 

Im: 

:rm 

Parameters 

Im 

The source-line character position at which to begin display of the line of source 
code (the left margin). 

rm 

The source-line character position at which to end display of the line of source 
code (the right margin). 

Description 

The SET MARGINS command affects only the display of source lines. It does not 
affect the display of other debugger output, as from an EXAMINE command. 

The SET MARGINS command is useful for controlling the display of source code 
when, for example, the code is deeply indented or long lines wrap at the right 
mar gin. In such cases, you can set the left margin to eliminate indented space in 
the source display, and you can decrease the right margin setting (from its default 
value of 255) to truncate lines and prevent them from wrapping. 

The SET MARGINS command is useful mostly in line (noscreen) mode. In line 
mode, the SET MARGINS command affects the display of source lines resulting 
from a TYPE, EXAMINE/SOURCE, SEARCH, or STEP command, or when a 
breakpoint, tracepoint, or watchpoint is triggered. 

In screen mode, the SET MARGINS command has no effect on the display of 
source lines in a source display, such as the predefined display SRC. Therefore it 
does not affect the output of a TYPE or EXAMINE/SOURCE command, since that 
output is directed at a source display. The SET MARGINS command affects only 
the display of any source code that might appear in an output or DO display (for 
example after a STEP command has been executed). However, such source-code 
display is normally suppressed if you invoke screen mode with the keypad key 
sequence PF1-PF3, because that sequence issues the SET STEP NOSOURCE 
command in addition to SET MODE SCREEN, to eliminate redundant source 
display. 

By default, the debugger displays a source line beginning at character position 1 
of the source line. This is actually character position 9 on your terminal screen. 
The first eight character positions on the screen are reserved for the line number 
and cannot be manipulated by the SET MARGINS command. 

If you specify a single number, the debugger sets the left margin to 1 and the 
right margin to the number specified. 
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Examples 




If you specify two numbers, separated with a colon, the debugger sets the left 
margin to the number on the left of the colon and the right margin to the number 
on the right. 

If you specify a single number followed by a colon, the debugger sets the left 
margin to that number and leaves the right margin unchanged. 

If you specify a colon followed by a single number, the debugger sets the right 
margin to that number and leaves the left margin unchanged. 

Related commands: 

SET STEP [NOJSOURCE 
SHOW MARGINS 


1. DBG> SHOW MARGINS 

left margin: 1 , right margin: 255 
DBG> TYPE 14 
module FORARRAY 

14: DIMENSION IARRAY(4:5,5), VECTOR(10), 130(3,3,4) 

DBG> 

This example displays the default margin settings for a line of source code (1 
and 255). 

2. DBG> SET MARGINS 39 
DBG> SHOW MARGINS 

left margin: 1 , right margin: 39 
DBG> TYPE 14 
module FORARRAY 

14: DIMENSION IARRAY(4:5,5), VECTOR 

DBG> 

This example shows how the display of a line of source code changes when 
you change the right margin setting from 255 to 39. 

3. DBG> SET MARGINS 10:45 
DBG> SHOW MARGINS 

left margin: 10 , right margin: 45 
DBG> TYPE 14 
module FORARRAY 

14: IMENSION IARRAY(4:5,5), VECTOR(10), 

DBG> 

This example shows the display of the same line of source code after both 
margins are changed. 

4. DBG> SET MARGINS :100 
DBG> SHOW MARGINS 

left margin: 10 , right margin: 100 
DBG> 

This example shows how to change the right margin setting while retaining 
the previous left margin setting. 
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5 . DBG> SET MARGINS 5: 

DBG> SHOW MARGINS 

left margin: 5 , right margin: 100 

DBG> 

This example shows how to change the left margin setting while retaining the 
previous right margin setting. 


4 
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SET MAX_SOURCE_FILES 

Specifies the maximum number of source files that the debugger can keep open at 
any one time. 


Format 

SET MAX_SOURCE_FILES integer 


Parameters 

integer 

A decimal integer specifying the maximum number of source files that the 
debugger can keep open at any one time. The value cannot exceed 20. The 
default is 5. 

Description 

By default, the debugger can keep five source files open at any one time. 

Opening a source file requires the use of an I/O channel, which is a limited 
system resource. Both the program and the debugger use I/O channels. To 
ensure that the debugger does not use all available I/O channels and thus cause 
the program to fail (for lack of an available I/O channel), you can enter the SET 
MAX_SOURCE_FILES command to specify the maximum number of source files 
(and thus source file I/O channels) that the debugger can use at any one time. 

The value of MAX_SOURCE_FILES does not limit the number of source files that 
the debugger can open; rather, it limits the number that can be kept open at any 
one time. Thus, if the debugger reaches this limit, it must close a file in order to 
open another one. 

Note also that setting MAX_SOURCE_FILES to a very small number can make 
the debugger’s use of source files inefficient. 

Related commands: 

(SET,SHOW,CANCEL) SOURCE 
SHOW MAX_SOURCE_FILES 

Example 

DBG> SHOW MAX_SOURCE_FILES 

max_source_files: 5 

DBG> SET MAX_SOURCE_FILES 8 

DBG> SHOW MAX_SOURCE_FILES 

max_source_files: 8 

DBG> 

In this example, the SET MAX_SOURCE_FILES 8 command enables the 
debugger to keep a maximum of eight files open at any one time. 
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SET MODE 

Format 

Parameters 


Enables or disables a debugger mode. 


SET MODE mode[, ... ] 


mode 

Specifies a debugger mode to be enabled or disabled. Valid keywords are as 
follows: 


DYNAMIC Enables dynamic mode. When dynamic mode is 

enabled, the debugger sets modules and images 
automatically during program execution so that you 
typically do not have to enter the SET MODULE 
or SET IMAGE command. Specifically, whenever 
the debugger interrupts execution (whenever 
the debugger prompt is displayed), the debugger 
automatically sets the module and image that 
contain the routine in which execution is currently 
suspended. If the module or image is already set, 
dynamic mode has no effect on that module or image. 
The debugger issues an informational message when 
its sets a module or image automatically. SET MODE 
DYNAMIC is the default. 

NODYNAMIC Disables dynamic mode. Because additional memory 

is allocated when a module or image is set, you 
might want to disable dynamic mode if performance 
becomes a problem (you can also free up memory by 
canceling modules and images with the CANCEL 
MODULE and CANCEL IMAGE commands). When 
dynamic mode is disabled, you must set modules and 
images explicitly with the SET MODULE and SET 
IMAGE commands. 

G_FLOAT Specifies that the debugger interpret double-precision 

floating-point constants entered in expressions as G_ 
FLOAT (does not affect the interpretation of variables 
declared in your program). 

NOG_FLOAT Specifies that the debugger interpret double-precision 

floating-point constants entered in expressions as D_ 
FLOAT (does not affect the interpretation of variables 
declared in your program). SET MODE NOG_FLOAT 
is the default. 
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INTERRUPT 

(Applies to a multiprocess debugging configuration— 
that is, when DBG$PROCESS has the value 
MULTIPROCESS.) Specifies that, when program 
execution is suspended in any process, the debugger 
interrupts execution in any other processes that were 
executing images and prompts for input. SET MODE 
INTERRUPT is the default. 

NOINTERRUPT 

(Applies to a multiprocess debugging configuration— 
that is, when DBG$PROCESS has the value 
MULTIPROCESS.) Specifies that, when program 
execution is suspended in any process, the debugger 
take the following action: 

• If execution was suspended because of an 
unhandled exception, the debugger interrupts 
execution in any other processes that were 
executing images and prompts for input. 

• If execution was suspended because of a 
breakpoint or watchpoint or the completion of 
a STEP command, the debugger lets execution 
proceed in any other processes that were 
executing images and does not display the prompt 
unless execution is eventually suspended in all 
these processes. As long as execution continues 
in any process, the debugger does not prompt for 
input. In such cases, use Ctrl/C to interrupt all 
processes and display the prompt. 

KEYPAD 

Enables keypad mode. When keypad mode is 
enabled, you can use the keys on the numeric keypad 
to perform certain predefined functions. Several 
debugger commands, especially useful in screen mode, 
are bound to the keypad keys (see Appendix B). You 
can also redefine the key functions with the DEFINE 
/KEY command. SET MODE KEYPAD is the default. 

NOKEYPAD 

Disables keypad mode. When keypad mode is 
disabled, the keys on the numeric keypad do not 
have predefined functions, nor can you assign 
debugger functions to those keys with DEFINE/KEY 
commands. 

LINE 

Specifies that the debugger display program locations 
in terms of line numbers, if possible. SET MODE 

LINE is the default. 

NOLINE 

Specifies that the debugger display program locations 
as routine-name + byte-offset rather than in terms of 
line numbers. 
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OPERANDS[=&ey word] 

NOOPERANDS 

SCREEN 

NOSCREEN 

SCROLL 

NOSCROLL 

SEPARATE 


NOSEPARATE 


Specifies that the EXAMINE command, when used 
to examine an instruction, display the address and 
contents of the instruction’s operands in addition 
to the instruction and its operands. The level of 
information displayed about any nonregister operands 
depends on whether you use the keyword BRIEF or 
FULL. The default is OPERANDS=BRIEF. 

Specifies that the EXAMINE command, when used to 
examine an instruction, display only the instruction 
and its operands. SET MODE NOOPERANDS is the 
default. 

Enables screen mode. When screen mode is enabled, 
you can divide the terminal screen into rectangular 
regions, so different data can be displayed in different 
regions. Screen mode enables you to view more 
information more conveniently than the default, line- 
oriented, noscreen mode. You can use the predefined 
displays, or you can define your own. 

Disables screen mode. SET MODE NOSCREEN is 
the default. 

Enables scroll mode. When scroll mode is enabled, 
a screen-mode output or DO display is updated by 
scrolling the output line by line, as it is generated. 
SET MODE SCROLL is the default. 

Disables scroll mode. When scroll mode is disabled, 
a screen-mode output or DO display is updated only 
once per command, instead of line by line as it is 
generated. Disabling scroll mode reduces the amount 
of screen updating that takes place and can be useful 
with slow terminals. 

(Applies only to workstations running VWS.) Specifies 
that a separate window be created for debugger input 
and output. This feature is useful when debugging 
screen-oriented programs, because it moves all 
debugger displays out of the window that contains the 
program’s input and output. The separate window is 
created with a height of 24 lines and a width of 80 
columns wide, emulating a VT-series terminal screen. 
(Applies only to workstations running VWS.) Specifies 
that no separate window be created for debugger 
input and output. SET MODE NOSEPARATE is the 
default. 
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Description 


Example 


SYMBOLIC Enables symbolic mode. When symbolic mode is 

enabled, the debugger displays the locations denoted 
by address expressions symbolically (if possible) 
and displays instruction operands symbolically (if 
possible). EXAMINE/NOSYMBOLIC can be used to 
override SET MODE SYMBOLIC for the duration of 
an EXAMINE command. SET MODE SYMBOLIC is 
the default. 

NOSYMBOLIC Disables symbolic mode. When symbolic mode is 

disabled, the debugger does not attempt to symbolize 
numeric addresses (it does not cause the debugger 
to convert numbers to names). This is useful if 
you are interested in identifying numeric addresses 
rather than their symbolic names (if symbolic names 
exist for those addresses). When symbolic mode 
is disabled, command processing might speed up 
somewhat, because the debugger does not need to 
convert numbers to names. EXAMINE/SYMBOLIC 
can be used to override SET MODE NOSYMBOLIC 
for the duration of an EXAMINE command. 


See the parameter descriptions for details about the SET MODE command. The 
default values of these modes are the same for all languages. 

Related commands: 


EVALUATE 

EXAMINE 

DEFINE/KEY 

DEPOSIT 

DISPLAY 

(SET,SHOW,CANCEL) IMAGE 
(SET,SHOW,CANCEL) MODULE 
SET PROMPT 

(SET,SHOW,CANCEL) RADIX 
(SET,SHOW) TYPE 
(SHOW,CANCEL) MODE 
SYMBOLIZE 


DBG> SET MODE SCREEN 

This command puts the debugger in screen mode. 
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SET MODULE 

Loads the symbol records of a module in the current image into the run-time 
symbol table (RST) of that image. 


Format 

SET MODULE [module-name[, ... ]] 

Parameters 


module-name 

Specifies a module of the current image whose symbol records are loaded into 
the RST. Do not use the asterisk (*) wildcard character. Instead, use the /ALL 
qualifier. Do not specify a module name with /ALL. 

Qualifiers 

/ALL U 1 

Specifies that the symbol records of all modules in the current image be loaded 
into the RST. Do not specify a module name with /ALL. 

/CALLS , , „ 

Sets all the modules that currently have routines on the call stack. If a module is 

already set, /CALLS has no effect on that module. Do not specify a module name 
with /CALLS. 

/RELATED (default) 

/NORELATED 

Applies to Ada programs. 

Controls whether the debugger loads into the RST the symbol records of a 
module that is related to a specified module through a with-clause or subumt 
relationship. 

SET MODULE/RELATED loads symbol records for related modules as well as 
for those specified. This makes names declared in related modules visible so that 
you can reference them in debugger commands exactly as they can be referenced 
within the Ada source code. SET MODULE/NORELATED loads symbol records 
only for modules that are specified (no symbol records are loaded for related 
modules). 


Description 


__ Note-—- 

The current image is either the main image (by default) or the image 
established as the current image by a previous SET IMAGE command. 


Symbol records must be present in the run-time symbol table (RST) if the 
debugger is to recognize and properly interpret the symbols declared in your 
program. The process by which the symbol records of a module are loaded into 
the RST is called setting a module. 
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Examples 


At debugger startup, the debugger sets the module containing the transfer 

rr^f ^ am P rogram ' ) - By default - dynamic mode is enabled (SET MODE 
YNAMIC). Therefore, the debugger sets modules (and images) automatically 
as .® P r °& ram executes so that you can reference symbols as you need them 
Specifically, whenever execution is suspended, the debugger sets the module and 
image contaimng the routine in which execution is suspended. In the case of 
Ada programs as a module is set dynamically, its related modules are also set 
automatically, by default, to make the appropriate symbols accessible (visible). 

Dynamic mode makes accessible most of the symbols you might need to reference 
foUows 1166 * 1 to reference a symbo1 in a m °dule that is not already set, proceed as 

If the module is in the current image, use the SET MODULE command to set 
the module where the symbol is defined. 

• If the module is in another image, use the SET IMAGE command to make 
that image the current image, then use the SET MODULE command to set 
the module where the symbol is defined. 

If dynamic mode is disabled (SET MODE NODYNAMIC), only the module 

containing the transfer address is set automatically. You must set any other 
modules explicitly. 

If you use the SET IMAGE command to establish a new current image all 
modules previously set remain set. However, only the symbols in the set modules 
of the current image are accessible. Symbols in the set modules of other images 
are temporarily unaccessible. 

When dynamic mode is enabled, memory is allocated automatically to 
accommodate the increasing size of the RST. If dynamic mode is disabled, the 
debugger automatically allocates more memory as needed when you set a module 
or an image. Whether dynamic mode is enabled or disabled, if performance 
becomes a problem as more modules are set, use the CANCEL MODULE 
command to reduce the number of set modules. 

If a parameter in a SET SCOPE command designates a program location in a 
module that is not already set, the SET SCOPE command sets that module. 

See Section E.1.14 for information specific to Ada programs. 

Related commands: 

(SET,SHOW,CANCEL) IMAGE 
SET MODE [NOJDYNAMIC 
(SHOW,CANCEL) MODULE 


1. DBG> SET MODULE SUB1 

This command sets module SUB1 (loads the symbol records of module SUB1 
into the Ko 1). 
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2. DBG> SET IMAGE SHARE3 
DBG> SET MODULE MATH 
DBG> SET BREAK %LINE 31 

In this example, the SET IMAGE command makes shareable image SHARE3 
the current image. The SET MODULE command sets module MATH in 
image SHARE3. The SET BREAK command sets a breakpoint on line 31 ot 

module MATH. 


3. DBG> SHOW MODULE/SHARE 
module name 

F00 

MAIN 


symbols 

language £ 

yes 

MACRO 

no 

FORTRAN 

no 

Image 

no 

Image 

no 

Image 

no 

Image 

no 

Image 

bytes allocated: 


size 

432 

280 


0 

0 

0 

0 

0 


SHARE$DEBUG 
SHARE$LIBRTL 
SHARE$MTHRTL 
SHARE$SHARE1 
SHARESSHARE2 

total modules: 17. 

DBG> SET MODULE SHARESSHARE2 
DBG> SHOW SYMBOL * IN SHARESSHARE2 

In this example, the SHOW MODULE/SHARE command identifies all 
modules in the current image and all shareable images (the names 
of the shareable images are prefixed with "SHARE$"). The SET 
MODULE SHARE$SHARE2 command sets the shareable image module 
SHARE$SHARE2. The SHOW SYMBOL command identifies any universal 
symbols defined in the shareable image SHARE2. See the description of t e 
/SHARE qualifier of the SHOW MODULE command for more information. 
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SET OUTPUT 


Format 


Enables or disables a debugger output option. 


SET OUTPUT output-option[, ... ] 

Parameters 


output-option 


Specifies an output option to be enabled or disabled. Valid keywords are as 
follows: 


LOG 

NOLOG 

SCREENLOG 


N OSCREEN_LOG 
TERMINAL 
NOTERMINAL 
VERIFY 

NOVERIFY 


Specifies that debugger input and output be recorded 
in a log file. If you specify the log file by the SET LOG 
command, the debugger writes to that file; otherwise, by 
default the debugger writes to SYS$DISK[ ]:DEBUG.LOG. 

Specifies that debugger input and output not be recorded in 
a log file. NOLOG is the default. 

Specifies that, while in screen mode, the screen contents be 
recorded in a log file as the screen is updated. Tb log the 
screen contents you must also specify SET OUTPUT LOG. 
See the description of the LOG option regarding specifying 
the log file. 

Specifies that the screen contents, while in screen mode not 
be recorded in a log file. NOSCREENLOG is the default. 

Specifies that debugger output be displayed at the terminal. 
TERMINAL is the default. 

Specifies that debugger output, except for diagnostic 
messages, not be displayed at the terminal. 

Specifies that the debugger echo, on the current output 
device, each input command string that it is executing from 
a command procedure or DO clause. The current output 
device is by default SYS$OUTPUT, the terminal, but can be 
redefined with the logical name DBG$OUTPUT. 

Specifies that the debugger not display each input command 
string that it is executing from a command procedure or DO 
clause. NOVERIFY is the default. 


Description 


Debugger output options control the way in which debugger responses to 
commands are displayed and recorded. See the parameter descriptions for 
details about the SET OUTPUT command. 

Related commands: 


@ (Execute Procedure) 
(SET,SHOW) ATSIGN. 
(SET,SHOW) LOG 
SET MODE SCREEN 
SHOW OUTPUT 
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Example 

DBG> SET OUTPUT VERIFY,LOG,NOTERMINAL 

This command specifies that the debugger take the following action. 

• Output each command string that it is executing from a command procedure 
or DO clause (VERIFY) 

• Record debugger output and user input in a log file (LOG) 

• Not display output at the terminal, except for diagnostic messages 
(NOTERMINAL) 
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SET PROCESS 


Establishes the visible process, changes characteristics of one or more processes, 
or enables/disables dynamic process setting. 

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 


Format 

SET PROCESS [process-spec[, ... ]] 

Parameters 


process-spec 

Specifies a process. Use any of the following forms: 


[%PROCESS_NAME] process-name 

[%PROCESS_NAME] "process-name 

%PROCESS_PID processed 

%PROCESS__NUMBER proc-number 
(or %PROC proc-number) 

process-group-name 

%NEXTJPROCESS 
%PREVIOUS_PROCESS 

%VISIBLE_PROCESS 

You can also use the asterisk 


The VMS process name, if that 
name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 

The VMS process name, if that name 
contains space or lowercase characters. 
You can also use apostrophes (') instead 
of quotation marks ( M ). 

The VMS process identification number 
(PID, a hexadecimal number). 

The number assigned to a process 
when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. Do not 
specify a recursive symbol definition. 

The process after the visible process in 
the debugger’s circular process list. 

The process previous to the visible 
process in the debugger’s circular 
process list. 

The process whose call stack, register 
set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 

processes. 


(*) wildcard character to specify all 
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Qualifiers 

/ALL 

Applies the SET PROCESS command to all processes. Do not specify a process 
with this qualifier. Do not specify /[NOJDYNAMIC, or /VISIBLE with /ALL. 

/DYNAMIC (default) 

/NODYNAMIC . ttti_ 

Controls whether dynamic process setting is enabled or disabled. When dynamic 

process setting is enabled (/DYNAMIC), whenever the debugger suspends 
execution and displays its prompt, the process in which execution is suspended 
becomes the visible process automatically. When dynamic process setting is 
disabled (/NODYNAMIC), the visible process remains unchanged until you 
specify another process with the SET PROCESS/VISIBLE command. 

Do not specify a process with /[NOJDYNAMIC. Do not specify /ALL, /[NOJHOLD, 
or /VISIBLE with /[NO]DYNAMIC. 

/HOLD 

/NOHOLD . 

/HOLD puts a specified process on hold. This prevents images in that process 
from executing when you enter a GO, STEP, or CALL command, unless the 
process is the visible process. A hold condition in the visible process is ignored. 

The /NOHOLD qualifier releases a specified process from a hold condition. This 
permits images in that process to execute when you enter a GO, STEP, or CALL 
command, regardless of which process is the visible process. 

The behavior described also applies when you use the DO command to broadcast 
a GO, STEP, or CALL command to specific processes. 

If no process is specified, /HOLD puts the visible process on hold, and /NOHOLD 
releases the visible process from the hold condition. 

See the descriptions of the GO, STEP, CALL, EXIT, and QUIT commands for the 
effects of these commands on processes that have or have not been put on hold. 

Do not specify /[NO]DYNAMIC with /[NO]HOLD. 

/VISIBLE 

Makes the specified process the visible process. This switches your debugging 
context to the specified process, so that symbol lookups and the setting of 
breakpoints, and so on, are done in the context of that process. You must specify 
one, and only one, process. 

If you do not specify /VISIBLE, it is assumed by default. 

Do not specify /ALL, or /[NOJDYNAMIC with /VISIBLE. 

Description 

The SET PROCESS command establishes the visible process or changes 
characteristics of one or more processes. 

By default, commands are executed in the context of the visible process. The 
visible process is the process that is your current debugging context. Symbol 
lookups and the setting of breakpoints, and so on, are done in the context of the 
visible process. 
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The DO command enables you to execute commands in the context of specific 
processes or of all processes. The DO command is equivalent to entering a SET 
PROCESS/VISIBLE command for each process specified (or for all processes, if 
no process is specified with the DO command) and then entering the specified 
commands. 

Dynamic process setting is enabled by default and is controlled with the 
/[NOJDYNAMIC qualifier. When dynamic process setting is enabled, whenever 
the debugger suspends program execution and displays its prompt, the process in 
which execution is suspended becomes the visible process automatically. 

Related commands: 

CALL 

DO 

EXIT 

GO 

QUIT 

SHOW PROCESS 
STEP 


Examples 


1. DBG_1> SET PROCESS/HOLD/ALL 
DBG_1> SHOW PROCESS/ALL 

Number Name Hold State Current PC 

1 TEST_X YES step PROGULINE 50 

2 TEST Y YES break PROGULINE 71 

DBG_1> 

The SET PROCESS/HOLD/ALL command puts all processes on hold This is 
confirmed in the SHOW PROCESS/ALL display. 

2. DBG_1> SET PROCESS/NOHOLD %VISIBLE PROCESS 
DBG_1> SHOW PROCESS/ALL 

Number Name Hold State Current PC 

1 TEST_X step PROGULINE 50 

2 TEST_Y YES break PROGULINE 71 

DBG_1> 

The SET PROCESS/NOHOLD %VISIBLE_PROCESS command releases 
the visible process from the hold condition. This is confirmed in the SHOW 
PROCESS/ALL display. 

3. DBG_1> SET PROCESS TEST Y 
DBG_2> SHOW PROCESS 

Number Name Hold State Current PC 

* 2 TEST_Y YES break PROGULINE 71 

DBG_2> 

The SET PROCESS TEST_Y command makes process TEST_Y the visible 
process. The SHOW PROCESS command displays information about the 
visible process by default. 
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4. DBG_1> SET PROCESS/HOLD/ALL 
DBG_1> DO (EXAMINE X; STEP) 

For %PROCESS_NUMBER 1 
MAIN_PROG\X: 78 

For %PROCESS_NUMBER 2 
TEST\X: 29 

stepped to MAIN PR0G\%LINE 26 in %PROCESS__NUMBER 1 

26: K = K +“l 

DBG_1> 

The SET PROCESS/HOLD/ALL command puts all processes on hold. The DO 
command broadcasts the EXAMINE X and STEP commands to all processes 
(processes 1 and 2, in this example). The STEP command is executed in the 
context of process 1, because a hold condition in the visible process is ignored. 
Because process 2 is on hold, execution is inhibited in that process. 
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SET PROMPT 


Changes the debugger prompt string to your personal preference. 

Format 

SET PROMPT [prompt-parameter] 

Parameters 


prompt-parameter 

Specifies the new prompt string. If the string contains spaces, semicolons (;), or 
lowercase characters, you must enclose it in quotation marks () or apostrophes 
('). If you do not specify a string, the current prompt string remains unchanged. 

By default, the prompt string is DBG> for a nonmultiprocess debugging 
configuration (when the logical name DBG$PROCESS is undefined or has 
the value DEFAULT)'. 


By default, for a multiprocess debugging configuration (when DBG$PROCESS has 
the value MULTIPROCESS), the prompt string consists of a process-independent 
prefix (specified by prompt-parameter) and a process-specific suffix (specified 

by the /[NO]SUFFIX qualifier). The suffix changes automatically as the visible 
process changes. 


Qualifiers 


/SUFFIX[=process-identifier-typel 

/NOSUFFIX 

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 


The /SUFFIX qualifier enables "dynamic prompt setting". As a result, the 
prompt string includes a process-specific suffix that automatically identifies the 
visible process. This is the default behavior. 

The /NOSUFFIX qualifier disables dynamic prompt setting. As a result, the 
prompt string does not include a process-specific suffix and does not change when 
another process becomes the visible process. 

When you invoke the debugger with the RUN command to debug a multiprocess 
program, the prompt string is DBG_1> by default. This indicates that dynamic 
prompt setting is enabled and that the visible process is process 1 (the first 
process connected to the debugger). You can control the process-specific prompt- 
string suffix by specifying one of the following process-identifier-type keywords 
with the /SUFFIX qualifier: 


PROCESS_NAME 

PROCESSJNTUMBER 

PROCESS_PID 


The display-name suffix is the VMS process name. 

The display-name suffix is the process number (as shown 
in a SHOW PROCESS display). 

The display-name suffix is the VMS process 
identification number (PID). 
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The following table illustrates the possible kinds of prompt strings for a 
multiprocess debugging configuration. The entire prompt string depends on t e 
prompt-parameter command parameter (which controls the process-independen 
prefix), and on the values of/[NO]SUFFIX and the process-identifier-type keyword 
(which control the process-specific suffix). 


Prompt Parameter 
(Prefix) 

Qualifier and Keyword (Suffix) 

Resulting Prompt String 

none 

none 

unchanged 

none 

/NOSUFFIX 

DBG> 

none 

/SUFFIX 

DBG _process-number> 1 

none 

/SUFFIX=PROCESS_NAME 

process-name> 

none 

/SUFFIX=PROCESS_NUMBER 

process-number> 

none 

/SUFFIX=PROCESS_PID 

pid> 

XYZ_ 

/NOSUFFIX 

XYZ_> 

XYZ_ 

/SUFFIX 

XYZ _process-number> 

XYZ_ 

/SUFFIX=PROCESS_NAME 

XYZ _process-name> 

XYZ_ 

/SUFFEX=PROCESS_NUMBER 

XYZ _process-number> 

XYZ_ 

/SUFFEX=PROCESS_PID 

XYZ _pid> 

x The default prompt for a multiprocess debugging configuration is DBG _process-number>, which is 
equivalent to entering the following command: ,, nD „ „ 

DBG> SET PROMPT/SUFF][X=PROCESS NUMBER "DBG 


/POP 

/NOPOP (default) 

Applies only to workstations running VWS. 

The /POP qualifier causes the debugger window to pop over other windows and 
become attached to the keyboard when the debugger prompts for input. The 
/NOPOP qualifier disables this behavior (the debugger window is not popped 
over other windows and is not attached to the keyboard automatically when the 
debugger prompts for input). 

If you do not specify /POP or /NOPOP, the prompt behavior is set to /NOPOP. 


Description 


The SET PROMPT command enables you to tailor the debugger prompt string to 


r our individual preference. 

f you are using a multiprocess debugging configuration (when the logical name 
}BG$PROCESS has the value MULTIPROCESS), the /[NO]SUFFIX qualifier 
mables you to specify a process-specific prompt-string suffix. 


If you are using the debugger at a workstation, the /[NOJPOP qualifier enables 
you to control whether the debugger window is popped over other windows 
whenever the debugger prompts for input. 


Related commands: (SET,SHOW) PROCESS. 
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Examples 


1. DBG> SET PROMPT "$ " 

$ SET PROMPT "dbg: " 
dbg: SET PROMPT "DBG> " 
DBG> 


Ihe successive SET PROMPT commands change the 
“DBG>” to to “d b g then back to “DBG>”. 


debugger prompt from 


DBG_1> SET PROMPT/NOSUFFIX "dbg> " 
dbg> SET PROMPT/SUFFIX 

DBG_1> SET PROMPT/SUFFIX=PROCESS NUMBER "xyz " 
xyz_l> SET PROMPT/SUFFIX=PROCESS~NAME 
SMITH> SET PROMPT/SUFFIX=PROCESS _ NAME "John " 

John SMITH> SET PROMPT/SUFFIX=PROCESS PID 
20800E4D> 

The successive SET PROMPT commands show the effect of the /[NO]SUFFIX 
qualifier and the prompt-parameter string for multiprocess programs. 
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SET RADIX 


Establishes the radix for the entry and display of integer data. When used with 
/OVERRIDE, causes all data to be displayed as integer data of the specified radix. 


Format 


SET RADIX radix 


Parameters 


radix 


Specifies the radix to be established. Valid keywords are as follows: 


BINARY 

DECIMAL 

DEFAULT 

OCTAL 

HEXADECIMAL 


Sets the radix to binary. 

Sets the radix to decimal. This is the default for all 
languages except BLISS and MACRO. 

Sets the radix to the language default. 

Sets the radix to octal. 

Sets the default radix to hexadecimal. This is the default for 
BLISS and MACRO. 


Qualifiers 


Sets only the input radix (the radix for entering integer data) to the specified 
radix. 

Sets only the output radix (the radix for displaying integer data) to the specified 
radix. 

/OVERRIDE , , .. . .. 

Causes all data to be displayed as integer data of the specified radix. 


Description 


The current radix setting influences how the debugger interprets and displays 
integer data in the following contexts: 

• Integer data that you specify in address expressions or language expressions. 

. Integer data that is displayed by the EXAMINE and EVALUATE commands. 

The default radix for both data entry and display is decimal for all languages 
except BLISS and MACRO. It is hexadecimal for BLISS and MACRO. 

The SET RADIX command enables you to specify a new radix for data entry or 
display (the input radix and output radix, respectively). 

If you do not specify a qualifier, the SET RADIX command changes both the input 
and output radix. If you specify the /INPUT or /OUTPUT qualifier, the command 
changes the input or output radix, respectively. 

If you specify the /OVERRIDE qualifier, the SET RADIX command changes only 
the output radix but causes all data (not just data that has an integer type) to be 
displayed as integer data of the specified radix. 
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Examples 


?“*** " h ~" “J d with the 'OVERRIDE qualifier, the SET RADIX command 
enumerafrtpe e vS re “ l0n ” diSP ' ay ° f Mninte ^r valuee (such as real or 

S2S an H DE Ti T “ mmands hava ^ ***•« 

Lrff ARY ’/S E ? AI)ECI ^ L ’ and S0 on) that enable y° u t0 override, for the 

or SET RAJ^fOVERRroE^mmand. Pre ' d ° USly eS * ab ‘ iShed ** SET 

You can also use the built-in symbols %BIN, %DEC, %HEX, and %OCT in 

tWfnfi expressiaas and language expressions to specify that an integer literal 

“7 f houl . d be interpreted in binary, decimal, hexadecimal, or octal radix 
respectively (see Appendix D). ’ 

Related commands: 

DEPOSIT 

EVALUATE 

EXAMINE 

(SET,SHOW,CANCEL) MODE 
(SHOW,CANCEL) RADIX 


1. DBG> SET RADIX HEX 

This command sets the radix to hexadecimal. This means that, by default 
integer data is interpreted and displayed in hexadecimal radix. 

2. DBG> SET RADIX/INPUT OCT 

S f tS th ! radix for input t0 octaL This means that, by default, 
integer data that is entered is interpreted in octal radix. 

3. DBG> SET RADIX/OUTPUT BIN 

This command sets the radix for output to binary. This means that, by 
default, integer data is displayed in binary radix. 

4. DBG> SET RADIX/OVERRIDE DECIMAL 

This command sets the override radix to decimal. This means that, by 

d^ai toL^r a <S. JUSt data ^ haS 8,1 i ” teger tyPe) iS 38 
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SET SCOPE 


Format 

Parameters 


Qualifiers 


Establishes how the debugger looks up symbols (variable names, routine names ; 
line numbers, and so on) when a pathname prefix is not specified. 


SET SCOPE location^ ... ] 


Snote" a program region (scope) to be used for the interpretation of symbols that 
you specify without a pathname prefix. A location can be any of the followi g, 
unless you specify /CURRENT or /MODULE (see the qualifier descriptions). 


pathname prefix 


Specifies the scope denoted by the pathname prefix. A 
pathname prefix consists of the names of one or more 
nesting program elements (module, routine, block, 
and so on), with each name separated by a backslash 
character (\ ). When a pathname prefix consists of more 
than one name, list a nesting element to the left of the 
\ and a nested element to the right of the \. A common 
pathname prefix format is module\routine\block \. 

If you specify only a module name and that name is 
the same as the name of a routine, use the /MODULE 
qualifier; otherwise, the debugger assumes that you are 
specifying the routine. 

Specifies the scope denoted by the routine which is n 
levels down the call stack (n is a decimal integer). A 
scope specified by an integer changes dynamically as the 
program executes. The value 0 denotes the routine that 
is currently executing, the value 1 denotes the caller of 
that routine, and so on down the call stack. The defau 
scope search list is 0,1,2, .., ,n, where n is the number 
of calls in the call stack. 

\ Specifies the global scope—that is, the set of all program 

locations in which a global symbol is known. The 
definition of a global symbol and the way it is declared 
depends on the language. 

When you specify more than one location parameter, you establish a scope search 
S If the debugger cannot interpret the symbol using the first parameter it uses 
the nexUparameter, and continues using parameters in order o their specification 
until it successfully interprets the symbol or until it exhausts the parameter 
specified. 


/CURRENT 

Establishes a scope search list that is like the default search list (0,1 
but starts at the numeric scope specified as the command parame er. 
the PC scope, and n is the number of calls in the call stack. 


,2, ... ,n) 
Scope 0 is 
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When using SET SCOPE/CURRENT, note the following conventions and behavior: 

Th rett^nT r S u rCh liSt must be m eltect when the command is entered, 
store the default scope search hst, enter the command CANCEL SCOPE. 

* parameter 8pecaied be eee (and only one) decimal integer 

SsSs n SRc‘l;H h mdT mand T'f* 8 th f prededn ed source and instruction 
Whf,*! „k i d '? ST ’ eeePecttvely, to show the routine on the call stack in 
which symbol searches are to start. 

The default scope search list is restored when program execution is resumed. 

/MODULE 

Indicates that the name specified as the command parameter is a module name 

nam? 0 * a , r ° Utme Y ° U ^ t0 USe /M0DULE °nly * y ou specify a module 

coroutine* ^ Parameter and that module na ™ is the same as the name 


Description 


By default the debugger looks up a symbol specified without a pathname prefix 

fn the cl S T°r SGarCh ^ ° M • • n is the number of caHs 

taCk- T, hlS SC ° pe search list is based on the current PC value and 
ST miCa u f, the program executes. The default scope search list 
specifies that a symbol lookup such as "EXAMINE X" first looks for X in the 

loolsTn tbt 1S f urren « y executing (scope 0); if no X is visible there, the debugger 
looks in the caller of that routine (scope 1), and so on down the call stack- ifXis 

(RST^that m f bugger / earches the rest of the run-time symbol table 

T) that is, all set modules and the global symbol table (GST), if necessary. 

thiS SCOpe search list enables you to resolve ambiguities 

m a predictable, natural way that is consistent with language rules Butif vou 

techniques 688 3 ^ multiple times > use either of the following 

Specify the symbol with a pathname prefix. The pathname prefix consists 

Z; eS mg prograai ani ts (for example, module\routiru>\block ) that are 
necessary to specify the symbol uniquely. For example: 

DBG> EXAMINE MOD4\ROUT3\X 
DBG> TYPE MOD4\27 

Establish a new default scope (or a scope search list) for symbol lookup bv 
mean, of the SET SCOPE command. You can then apeci&fte °yiw Mftout 
using a pathname prefix. For example: 

DBG> SET SCOPE MOD4\ROUT3 
DBG> EXAMINE X 
DBG> TYPE 27 

The SET SCOPE command is useful in those cases where otherwise you would 
need to use a pathname repeatedly to specify symbols. 

To restore the default scope search list, use the CANCEL SCOPE command. 

SCOPF/TTTPPPmt? 156 Sea I Ch J ist is in effect ’ y° u can use the command SET 
SCOPE/CURRENT to specify that symbol searches start at a numeric scope other 
than scope 0, relative to the call stack (for example, scope 2) P 
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Examples 


When you use the SET SCOPE command, the debugger searches oriy the 
nroeram locations you specify explicitly, unless you use the /CURRENT qualifier. 
Also the scope or scope search list established with a SET SCOPE command 
remans in effect until you restore the default scope search list or enter another 
SET SCOPE command. However, if you use the /CURRENT qualifier, the defa 
scope search list is restored whenever program execution is resumed. 

The SET SCOPE command updates a screen-mode source or instruction display 
only if the command is used with the /CURRENT qualifier. 

If a name you specify in a SET SCOPE command is the name of both a module 
and a routine, the debugger sets the scope to the routine. In inch_cases,use 
SET SCOPE/MODULE command if you want to set the scope to the module. 

If you specify a module name in a SET SCOPE command, the debugger "sets" 
that module if it is not already set. However, if you want only to set a module, 
use the SET MODULE command rather than the SET SCOPE command, to avoi 
the possibility of disturbing the current scope search list. 

See Section E.1.12 and Section E.1.13 for information specific to Ada programs. 
Related commands: 


CANCEL ALL 

SEARCH 

SET MODULE 

(SHOW,CANCEL) SCOPE 

SHOW SYMBOL 

SYMBOLIZE 

TYPE 


l. 


dbg> examine y 

%DEBUG-W-NOUNIQUE, symbol 'Y' is not unique 
DBG> SHOW SYMBOL Y 
data CHECK_IN\Y 
data INVENTORY\COUNT\Y 
DBG> SET SCOPE INVENTORY\COUNT 

dbg> examine y 

INVENTORY\COUNT\Y: 347.15 


DBG> 

In this example, the first EXAMINE Y command indicates that symbol Y is 
defined multiple times and cannot be resolved from the current scope search 
list The SHOW SYMBOL command displays the different declarations o 
svmbol Y The SET SCOPE command directs the debugger to look for symbols 
rhout pathname prefixes in routine COUNT of module INVENTORY. The 
subsequent EXAMINE command can now interpret Y unambiguously. 


2 DBG> CANCEL SCOPE 

DBG> SET SCOPE/CURRENT 1 

Tn this example the CANCEL SCOPE command restores the default scope 
i^h \S7o i2 n) The SET SCOPE/CURRENT command then 
SSL 1 the wesetrl list to i,2, so that symbol searches start wfrh 

scope 2-that is with the caller of the routine in which exec ^ n a 1 "7™ tly 
suspended. The predefined source and instruction displays SRC and ™ ’ 

respectively, are updated and now show the source and instructions for the 
caller of the routine in which execution is suspended. 
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3. DBG> SET SCOPE 1 
DBG> EXAMINE %R5 

In S i GXa ^ Ple ’ thC SET SC0PE command directs the debugger to look for 
symbols without pathname prefixes in scope 2—that is, in the caller of the 

Zn « 6 6Xe , CUtl0n is sus Pended. The EXAMINE command then 

displays the value of register R5 in the caller routine. The SET SCOPE 
command, when used without the /CURRENT qualifier, does not update any 
source or instruction display. ^ ^ 

4. DBG> SET SCOPE 0, STACKS\R2, SCREEN 

This command directs the debugger to look for symbols without pathname 
fn tS e pp CC ° rdin S the /° llowin g SC0 P e search list. First the debugger looks 
r P pr ted by ,"°" X If the debugger cannot find a specified 
ymbol in the PC scope, it then looks in routine R2 of module STACKS If 

If the debugger stm cannot find 


global X 
local X 

same as ALPHA\X 


5. DBG> SHOW SYMBOL X 
data ALPHA\X 
data ALPHA\BETA\X 
data X (global) 

DBG> SHOW SCOPE 
scope: 0 [ = ALPHA\BETA ] 

DBG> SYMBOLIZE X 
address ALPHA\BETA\IRO: 

ALPHA\BETA\X 
DBG> SET SCOPE \ 

DBG> SYMBOLIZE X 
address 00000200: 

ALPHA\X 

address 00000200: (global) 

X 

DBG> 

. exa 7 le ' -SHOW SYMBOL command indicates that there are 

V ^ < ab °wn twice) and a 

(ALPHAXRrT? current ““I* the local declaration ofX 

SmPF \\ B fh TA \ X k '? r S ! Me ' Afler the scope is set *° thc S lobal ““PC (SET 
SCOPE \), the global declaration of X is made visible. 
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SET SEARCH 


Establishes default qualifiers (/ALL or /NEXT, /IDENTIFIER or /STRING) for the 
SEARCH command. 

Format 

SET SEARCH search-default[, ... ] 


Parameters 


l^elfdeLt to be established for the SEARCH command. Valid keywords 
(which correspond to SEARCH command qualifiers) are as follows: 


ALL 


IDENTIFIER 

NEXT 

STRING 


Subsequent SEARCH commands are treated as SEARCH/ALL, 
rather than SEARCH/NEXT. 

Subsequent SEARCH commands are treated as SEARCH 
/IDENTIFIER, rather than SEARCH/STRING. 

Subsequent SEARCH commands are treated as SEARCH/NEXT, 
rather than SEARCH/ALL. This is the default. 

Subsequent SEARCH commands are treated as SEARCH 
/STRING, rather than SEARCH/IDENTIFIER. This is the 

Hckfcmlt. 


Description 


The SET SEARCH command establishes default qualifiers for subsequent 
SEARCH commands. The parameters that you specify in the 
command have the same names as the SEARCH command qualifier* The 
qualifiers determine whether the SEARCH command: 

occurrences (ALL) of a string or only the next occurrence (NEXT), and ( ) 
displays any occurrence of the string (STRING) or only those occurrences in 
SX sU is not bounded on ^r “do by a .character that can be part of 
an identifier in the current language (IDENTIFIER). 

You can override the current SEARCH default for the duration# a g j^ H 
SEARCH command by specifying other qualifiers. Use the SHOW SEARO 
Mvmmnnd to identify the current SEARCH defaults. 


Related commands: 

SEARCH 

(SET,SHOW) LANGUAGE 
SHOW SEARCH 
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Example 


dbg> show search 

search settings: search for 

DBG> SET SEARCH IDENTIFIER 

DBG> SHOW SEARCH 

search settings: search for 

DBG> SET SEARCH ALL 

DBG> SHOW SEARCH 

search settings: search for 

DBG> 


next occurrence, 
next occurrence, 
all occurrences, 


as a string 
as an identifier 
as an identifier 


In this example, the SET SEARCH IDENTIFIER command directs the debugger 
to search for an occurrence of the string in the specified range but display the 

ring only if it is not bounded on either side by a character that can be part of 
an identifier in the current language. ^ 


The SET SEARCH ALL command directs the debugger 
all occurrences of the string in the specified range. 


to search for (and display) 
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SET SOURCE 

Specifies where the debugger is to search for source files that have been moved to 
another directory after being compiled. 


Format 

SET SOURCE directory-spec[, ... ] 


Parameters 


Specifies 7 any part of a VMS file specification (typically a device/directory) that 
the debugger is to use by default when searching for a source file. For any 
part of a full file specification that you do not supply, the Rugger uses the 
specification stored in the module’s symbol record—that is, the file specification 
that the source file had at compile time. 

If you specify more than one directory in a single SET SOURCE command you 
create a source directory search list (you can also specify a search list logical 
name that is defined at your process level). In this case, the debugger locate> the 
source file by searching the first directory specified, then the second, and so on, 
until it either locates the source file or exhausts the list of directories. 


Qualifiers 


/ EDIT 

Applies mainly to Ada programs. 

Specifies that the directory search list is used to locate source 
when you use the EDIT command. 


files for editing 


/MODULE=module-name 

Specifies that the directory search list is used to locate source 
specified module. 


files 


only for the 


Description 


By default, the debugger expects a source file to be in the same directory it was 
in at compile time (the debugger also checks that the creation and revis on date 
and time of a source file match the information in the debugger s symbol table). 

If a source file has been moved to a different directory since compile time, use the 
SET SOURCE command to specify a source directory search list. 

When a source file is moved to another directory, the version number of the source 
file might change. To locate the correct version of the source file in the event that 
a versSn number was not specified in the directory-spec parameter, the debugger 
inserts the match-all asterisk (*) wildcard character m the version number field 
of the new file specification. Therefore, all versions of the moved source file are 
searched until the correct version is located. The correct verson ,ofthe source 
file is the version that has the same creation or revision date and time, the same 
file size, the same record format, and the same file organization as the original 
compile-time source file. 
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If the debugger does not find the correct version, it uses the file that has the 
dosest revision date and time (if such a file exists in that Ws a 

message such as the following when first displaying source code 

%DEBUG-I-NOTORIGSRC, original version of source file not found 
file used is WORK:[JONES.PR0G3JPRG.FOR;14 

auahfie^hVll^ 7 S0URC ? command without the MODULE=module-name 

files for ? CS tHe specified Rectory search list to locate source 

MODULP Z t r ^ n0t mentioned in a Previous SET SOURCE 
/lvivjjju Lthj=moaule-name command. 

See the qualifier descriptions for an explanation of their effects. 

^alifier is needed when the files used for the display of source code 
• r ®, dlfferent ir° m the files to be edited by means of the EDIT command This 

SOURCEcZm A ? P L 0g ! a ^ S ' F ° r Ada Programs, the (SET, SHOW, CANCEL) 
commands affect the search of files used for source display (the "copied" 
source files m Ada program libraries); the (SET,SHOW,CANCEL) SOURCE/EDIT 
commands affect the search of the source files you edit when using the EDIT 

See Section E.1.5 and Section E.1.6 for information specific to Ada programs. 

A full VMS file specification consists of the following fields: 

node::device:[directory]file-name.file-type;version-number 

0f a S T Ce ffle exceeds 231 chara cters, the debugger 
name i ^ ^T i Z™* ar ° Und this problem hy first ^fining a fogical 
the command S SOTOCeT * ^ Spedfi - tion > a » d *en using 

When compiling a program with the /DEBUG qualifier, if you use a rooted- 
directory logical name to specify the location of the source file, make sure that it 
lsacortceo/ed rooted-directory logical name. If it is not concealed and you move 

debuggeTsET SOSSoT compilation, you cannot then use the 

debugger SET SOURCE command to specify the new location of the source file. 

l0giCaI name ' use the 8ynt “ 

$ DEFINE/TRANSLATION_ATTR=CONCEAL ROOTDIR DISK3$:[USER.DIR1.] 

Related commands: 

(CANCEL,SHOW) MAX SOURCE F TT .P S 
(CANCEL,SHOW) SOURCE 


Examples 


1. DBG> SHOW SOURCE 

no directory search list in effect 

ro IP ’ ,0J1, ' [raoJB) ' “ SEES: wra.PRojcj 

source directory search list for all modules: 

[PROJA] 

[PROJB] 

USERS:[PETER.PR0JC1 

DBG> 
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In this example, the SET SOURCE command specifiesti* debugger 
should search directories [PROJA], [PROJB], and USER$.[PETER.PROJCJ, in 
that order, for source files. 

DBG> SET SOURCE/MODULE=COBOLTEST [], DISK$2:[PROJD] 

DBG> SHOW SOURCE 

source directory search list for COBOLTEST: 

[] 

DISK$2:[PROJD] 

source directory search list for all other modules. 

[PROJA] 

[PROJB] 

USERS:[PETER.PROJC] 

DBG> 

In this example, the SET SOUR°E command spedfies that the deeper 

should search the current default directory (11) and DISmiPROJDl 
that order, for source files to use with the module COBOLTEbi. lhe &nuv» 
SOURCE command displays the search lists established in examp es an 
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SET STEP 

Establishes default qualifiers (/LINE, /INTO, and so on) for the STEP command. 

Format 

SET STEP step-default[, ... ] 

Parameters 

step-default 

Specifies a default to be established for the STEP command. Valid keywords 
(which correspond to STEP command qualifiers) are as follows: 

BRANCH Subsequent STEP commands are treated as STEP/BRANCH 


CALL 

(step to the next branch instruction). 

Subsequent STEP commands are treated as STEP/CALL (step 
to the next call instruction). 

EXCEPTION 

Subsequent STEP commands are treated as STEP 
/EXCEPTION (step to the next exception). 

INSTRUCTION 

Subsequent STEP commands are treated as STEP 
/INSTRUCTION (step to the next instruction). 

You can also specify one or more instructions 
(/INSTRUCTION[=(opco<ie . . . )]). The debugger then steps to 
the next instruction that is in the specified list. If you specify 
a vector instruction, do not include an instruction qualifier (/U, 
/V, /M, /0, or /l) with the instruction mnemonic. 

INTO 

Subsequent STEP commands are treated as STEP/INTO 
(step into called routines) rather than STEP/OVER (step over 
called routines). When INTO is in effect, you can qualify 
the types of routines to step into by means of the [NO]JSB, 
[NO]SHARE, and [NOJSYSTEM parameters, or by using the 
STEP/[NO]JSB, STEP/[NO]SHARE, and STEP/[NO]SYSTEM 
command/qualifier combinations (the latter three take effect 
only for the immediate STEP command). 

JSB 

If INTO is in effect, subsequent STEP commands are treated 
as STEP/INTO/JSB (step into routines called by a JSB 
instruction as well as those called by a CALL instruction). 

This is the default for all languages except DIBOL. 

NOJSB 

If INTO is in effect, subsequent STEP commands are treated 
as STEP/INTO/NOJSB (step over routines called by a 

JSB instruction, but step into routines called by a CALL 
instruction). This is the default for DIBOL. 

LINE 

Subsequent STEP commands are treated as STEP/LINE (step 
to the next line). This is the default for all languages. 

OVER 

Subsequent STEP commands are treated as STEP/OVER (step 
over all called routines) rather than STEP/INTO (step into 
called routines). SET STEP OVER is the default. 
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If you specify an absolute address for the address expression, the debugger might 
not be able to associate the address with a particular data object. In this case, the 
debugger uses a default length of 4 bytes. You can change this length, however, 
by setting the type to either WORD (SET TYPE WORD, which changes the 
default length to 2 bytes) or BYTE (SET TYPE BYTE, which changes the default 
length to 1 byte). SET TYPE LONGWORD restores the default length of 4 bytes. 

/OVER 

Applies only to tracepoints set with the following qualifiers—that is, when an 
address expression is not explicitly specified: 

/BRANCH 

/CALL 

/INSTRUCTION[=(opcoofe .. . )] 

/LINE 

/VECTOR_INSTRUCTION 

When used with those qualifiers, causes the debugger to trace the specified 
points only within the routine in which execution is currently suspended (not 
within called routines). The /OVER qualifier is the opposite of /INTO (the default 
behavior). 

/RETURN 

Causes the debugger to trace the RET (return) instruction of the routine 
associated with the specified address expression (which can be a routine name, 
line number, and so on). This qualifier can only be applied to routines called with 
a CALLS or CALLG instruction; it cannot be used with JSB routines. Tracing the 
RET instruction enables you to inspect the local environment (for example, obtain 
the values of local variables) before the RET instruction deletes the routine’s call 
frame from the call stack. 

For this qualifier, the address-expression parameter is an instruction address 
within a CALLS or CALLG routine. It can simply be a routine name, in which 
case it specifies the routine start address. However, you can also specify another 
location in a routine, so you can see only those returns that are taken after a 
certain code path is followed. 

A SET TRACE/RETURN command cancels a previous SET TRACE command if 
the same address expression is specified. 

/SHARE (default) 

/NOSHARE 

Qualifies /INTO. Use /[NOJSHARE only with /INTO and one of the following 
qualifiers: 

/BRANCH 

/CALL 

/INSTRUCTION[=(qpcocte . . . )] 

/LINE 

/VECTOR_IN STRU CTION 

The /SHARE qualifier permits the debugger to set tracepoints within shareable 
image routines as well as other routines. The /NOSHARE qualifier specifies 
that tracepoints not be set within shareable images. Do not specify an address 
expression with /[NOJSHARE. 
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/SILENT 

/NOSILENT (default) 

Controls whether the "trace ..." message and the source line for the current 
location are displayed at the tracepoint. The /NOSILENT qualifier specifies that 
the message is displayed. The /SILENT qualifier specifies that the message and 
source line are not displayed. The /SILENT qualifier overrides /SOURCE. 

/SOURCE (default) 

/NOSOURCE 

Controls whether the source line for the current location is displayed at the 
tracepoint. The /SOURCE qualifier specifies that the source line is displayed. 
The /NOSOURCE qualifier specifies that the source line is not displayed. The 
/SILENT qualifier overrides /SOURCE. See also SET STEP [NOJSOURCE. 

/SYSTEM (default) 

/NOSYSTEM 

Qualifies /INTO. Use /[NO]SYSTEM only with /INTO and one of the following 
qualifiers: 

/BRANCH 

/CALL 

/INSTRUCTION[=(opcocfe . . . )] 

/LINE 

/VECTOR.INSTRUCTION 

The /SYSTEM qualifier permits the debugger to set tracepoints within system 
routines (PI space) as well as other routines. The /NOSYSTEM qualifier specifies 
that tracepoints not be set within system routines. Do not specify an address 
expression with /[NOJSYSTEM. 

/TEMPORARY 

Causes the tracepoint to disappear after it is triggered (the tracepoint does not 
remain permanently set). 

/TERMINATING 

Causes the debugger to trace when a process does an image exit. This is the 
default behavior. The debugger always gains control and displays its prompt 
when the last image of a one-process or multiprocess program exits. Do not 
specify an address expression with /TERMINATING. See also /ACTIVATING. 

/VECTORJNSTRUCTION 

Causes the debugger to trace every vector instruction encountered during 
program execution. Do not specify an address expression with /VECTOR_ 
INSTRUCTION. See also /INTO and /OVER. 

Description 

When a tracepoint is triggered, the debugger takes the following action: 

1. Suspends program execution at the tracepoint location. 

2. If /AFTER was specified when the tracepoint was set, checks the AFTER 
count. If the specified number of counts has not been reached, execution is 
resumed and the debugger does not perform the remaining steps. 

3. Evaluates the expression in a WHEN clause, if one was specified when 
the tracepoint was set. If the value of the expression is false, execution is 
resumed and the debugger does not perform the remaining steps. 
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4. Reports that execution has reached the tracepoint location by issuing a 
"trace ..." message, unless /SILENT was specified. 

5. Displays the line of source code corresponding to the tracepoint, unless 
/NOSOURCE or /SILENT was specified when the breakpoint was set, or SET 
STEP NOSOURCE was entered previously. 

6. Executes the commands in a DO clause, if one was specified when the 
tracepoint was set. 

7. Resumes execution. 

You set a tracepoint at a particular location in your program by specifying an 
address expression with the SET TRACE command. You set a tracepoint on 
consecutive source lines, classes of instructions, or events by specifying a qualifier 
with the SET TRACE command. Generally, you must specify either an address 
expression or a qualifier, but not both. Exceptions are the /EVENT and /RETURN 
qualifiers. 

The /LINE qualifier sets a tracepoint on each line of source code. 

The following qualifiers set tracepoints on classes of instructions. Use of 
these qualifiers and of the /LINE qualifier causes the debugger to trace every 
instruction of your program as it executes and thus significantly slows down 
execution: 

/BRANCH 

/CALL 

/INSTRUCTION[=(opcocte[, ...])] 

/RETURN 

/VECTORJNSTRUCTION 

The following qualifiers set tracepoints on classes of events: 

/ACTIVATING 

/EVENT=even/-name 

/EXCEPTION 

/TERMINATING 

The following qualifiers affect what happens at a routine call: 

/INTO 

/[NO]JSB 

/OVER 

/[NOjSHARE 

/[NOISYSTEM 

The following qualifiers affect what output is displayed when a tracepoint is 
reached: 

/[NO]SILENT 

/[NOISOURCE 

The following qualifiers affect the timing and duration of tracepoints: 

/AFTER: n 
/TEMPORARY 

The /MODIFY qualifier is used to monitor changes at program locations (typically 
changes in the values of variables). 

If you set a tracepoint at a location currently used as a breakpoint, the breakpoint 
is canceled in favor of the tracepoint, and conversely. 
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Tracepoints can be user defined or predefined. User defined tracepoints are those 
that you set explicitly with the SET TRACE command. Predefined tracepoints, 
which depend on the type of program you are debugging (for example, Ada or 
multiprocess), are established automatically when you invoke the debugger. Use 
the SHOW TRACE command to identify all tracepoints that are currently set. 
Any predefined tracepoints are identified as such. 

User defined and predefined tracepoints are set and canceled independently. 

For example, a location or event can have both a user defined and a predefined 
tracepoint. Canceling the user defined tracepoint does not affect the predefined 
tracepoint, and conversely. 

Related commands: 

CANCEL ALL 
GO 

SET BREAK 

(SET,SHOW) EVENT.FACILITY 
SET STEP [NO]SOURCE 
SET WATCH 

(SHOW,CANCEL) TRACE 

Examples 

1. DBG> SET TRACE SUB3 

This command causes the debugger to trace the beginning of routine SUB3 
when that routine is executed. 

2. DBG> SET TRACE/BRANCH/CALL 

This command causes the debugger to trace every BRANCH instruction and 
every CALL instruction encountered during program execution. 

3. DBG> SET TRACE/LINE/INTO/NOSHARE/NOSYSTEM 

This command causes the debugger to trace the beginning of every source 
line, including lines in called routines (/INTO) but not in shareable image 
routines (/NOSHARE) or system routines (/NOSYSTEM). 

4. DBG> SET TRACE/NOSOURCE TEST5ULINE 14 WHEN (X .NE. 2) DO (EXAMINE Y) 

This command causes the debugger to trace line 14 of module TEST5 when 
X is not equal to 2. At the tracepoint, the EXAMINE Y command is issued. 
The /NOSOURCE qualifier suppresses the display of source code at the 
tracepoint. The syntax of the conditional expression in the WHEN clause is 
language-dependent. 

5. DBG> SET TRACE/INSTRUCTION WHEN (X .NE. 0) 

This command causes the debugger to trace when X is not equal to 0. The 
condition is tested at each instruction encountered during execution. The 
syntax of the conditional expression in the WHEN clause is language- 
dependent. 
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6. DBG> SET TRACE/SI LENT SUB2 DO (SET WATCH K) 

This command causes the debugger to trace the beginning of routine SUB2 
during execution. At the tracepoint, the DO clause sets a watchpoint on 
variable K. The /SILENT qualifier on the SET TRACE command suppresses 
the "trace ..." message and the display of source code at the tracepoint. 
This example shows a convenient way of setting a watchpoint on a nonstatic 
(stack or register) variable. A nonstatic variable is defined only when its 
defining routine (SUB2, in this case) is active (on the call stack). 

7. DBG> SET TRACE/RETURN ROUT4 DO (EXAMINE X) 

This command causes the debugger to trace the RET instruction of routine 
ROUT4 (that is, just before execution returns to the calling routine). At the 
tracepoint, the DO clause issues the EXAMINE X command. This example 
shows a convenient way of obtaining the value of a nonstatic variable just 
before execution leaves that variable’s defining routine. 

8. DBG> SET TRACE/EVENT=TERMINATED 

This command causes the debugger to trace the point at which any task 
makes a transition to the TERMINATED state. 
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SET TYPE 

Format 

Parameters 


Establishes the default type to be associated with program locations that do 
not have a symbolic name (and, therefore, do not have an associated compiler 
generated type). When used with /OVERRIDE, establishes the default type to be 
associated with all locations, overriding any compiler generated types. 


SET TYPE type-keyword 


type-keyword 

Specifies the default type to be established. Valid keywords are as follows: 

ASCIC Sets the default type to counted ASCII string with a 

1-byte count field that precedes the string and gives 
its length. AC is also accepted as a keyword. 

ASCID Sets the default type to ASCII string descriptor. 

The CLASS and DTYPE fields of the descriptor are 
not checked, but the LENGTH and POINTER fields 
provide the character length and address of the 
ASCII string. The string is then displayed. AD is 
also accepted as a keyword. 

ASCILra Sets the default type to ASCII character st ring 

(length n bytes). The length indicates both the 
number of bytes of memory to be examined and the 
number of ASCII characters to be displayed. If you 
do not specify a value for n, the debugger uses the 
default value of 4 bytes. The value n is interpreted in 
decimal radix. 


ASCIW 

ASCIZ 

BYTE 

D.FLOAT 


Sets the default type to counted ASCII string with a 
2-byte count field that precedes the string and gives 
its length. This data type occurs in PASCAL and 
PL/I. AW is also accepted as a keyword. 

Sets the default type to zero-terminated ASCII string. 
The ending zero byte indicates the end of the st ring 
AZ is also accepted as a keyword. 

Sets the default type to byte integer (length 1 byte). 

Sets the default type to D_floating (length 8 bytes). 
Values of type D_floating can range from .29 * 10 -38 
to 1.7 * 10 38 with approximately 16 decimal digits 
precision. 
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DATE_TIME 

FLOAT 

G. FLOAT 

H. FLOAT 

INSTRUCTION 

LONGWORD 

OCTAWORD 

PACKED:n 

QUADWORD 

TYPE=(expression) 

WORD 


Sets the default type to date and time. This is a 
quadword integer (length 8 bytes) containing the 
internal VMS representation of date and time. 

Values are displayed in the format dd-mmm-yyyy 
hh:mm:ss.xx. Specify an absolute date and time as 
follows: 

[dd-mmm-yyyy[:]] [hh:mm:ss.cc] 

Sets the default type to F_floating (length 4 bytes). 
Values of type F_floating can range from .29 * 10 -38 
to 1.7 * 10 38 with approximately 7 decimal digits 
precision. 

Sets the default type to G.floating (length 8 bytes). 
Values of type G_floating can range from .56 * io -308 
to .9 * 10 308 with approximately 15 decimal digits 
precision. 

Sets the default type to H_floating (length 16 bytes). 
Values of type H_floating can range from .84 * 10~ 4932 
to .59 * io 4932 with approximately 33 decimal digits 
precision. 

Sets the default type to VAX instruction (variable 
length, depending on the number of instruction 
operands and the kind of addressing modes used). 

Sets the default type to longword integer (length 4 
bytes). This is the default type for program locations 
that do not have a symbolic name (do not have a 
compiler generated type). 

Sets the default type to octaword integer (length 16 
bytes). 

Sets the default type to packed decimal. The value of 
n is the number of decimal digits. Each digit occupies 
one nibble (4 bits). 

Sets the default type to quadword integer (length 8 
bytes). 

Sets the default type to the type denoted by 
expression (the name of a variable or data type 
declared in the program). This enables you to specify 
an application-declared type. 

Sets the default type to word integer (length 2 bytes). 


Qualifiers 

/OVERRIDE 

Associates the type specified with all program locations, whether or not they have 
a symbolic name (whether or not they have an associated compiler generated 
type). 
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Description 


When you use the EXAMINE, DEPOSIT, or EVALUATE commands, the default 
types associated with address expressions influence how the debugger interprets 
and displays program entities. 


e debugger recognizes the compiler generated types associated with symbolic 
address expressions (symbolic names declared in your program), and it interprets 
and displays tk contents of these locations accordingly. For program locations 
that do not have a symbolic name and, therefore, no associated compiler 
generated type, the default type in all languages is longword integer. 

The SET TYPE command enables you to change the default type associated 
with locations that do not have a symbolic name. The SET TYPE/OVERRIDE 
command enables you to set a default type for all program locations, both those 
that do and do not have a symbolic name. 


/n he „??^ INE ; and DEPOSIT commands have type qualifiers (/ASCII, /BYTE, 
/(j_FLOAT, and so on) that enable you to override, for the duration of a s ing le 
command, the type previously associated with any program location. 

Related commands: 


CANCEL TYPE/OVERRIDE 

DEPOSIT 

EXAMINE 

(SET,SHOW,CANCEL) RADIX 
(SET,SHOW,CANCEL) MODE 
SHOW TYPE 


Examples 


1. DBG> SET TYPE ASCII:8 

This command establishes an 8-byte ASCII character string as the default 
type associated with untyped program locations. 

2. DBG> SET TYPE/OVERRIDE LONGWORD 

Tins command establishes longword integer as the default type associated 
with both untyped program locations and program locations that have 
compiler generated types. 

3. DBG> SET TYPE D_FL0AT 

This command establishes D.Floating as the default type associated with 
untyped program locations. 


4. DBG> SET TYPE TYPE= (S_ARRAY) 

This command establishes the type of the variable S.ARRAY as the default 
type associated with untyped program locations. 
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SET VECTOR_MODE 

Enables or disables a debugger vector mode option. 
Applies to vectorized programs. 

Format 

SET VECTOR_MODE vector-mode-option 


Parameters 

vector-mode-option 

Specifies the vector mode option. Valid keywords are as follows: 

SYNCHRONIZED Specifies that the debugger force automatic 

synchronization between the scalar and vector 
processors whenever a vector instruction is executed. 
Specifically, the debugger issues a SYNC instruction 
after every vector instruction and, in addition, an 
MSYNC instruction after any vector instruction that 
accesses memory. This forces the completion of all 
activities associated with the vector instruction that is 
being synchronized: 

• Any exception that was caused by a vector 
instruction is delivered before the next scalar 
instruction is executed. Forcing the delivery 
of a pending exception triggers an exception 
breakpoint or tracepoint (if one was set) or invokes 
an exception handler (if one is available at that 
location in the program). 

• Any read or write operation between vector 
registers and either the general registers or 
memory is completed before the next scalar 
instruction is executed. 

The SET VECTOR_MODE SYNCHRONIZED 
command does not issue an immediate SYNC or 
MSYNC instruction at the time it is issued. Use 
the SYNCHRONIZE VECTOR_MODE command to 
force immediate synchronization. 

NOSYNCHRONIZED Specifies that the debugger not force synchronization 

between the scalar and vector processors except 
for internal debugger purposes. As a result, any 
synchronization is controlled entirely by the program, 
and the program runs as if it were not under debugger 
control. NOSYNCHRONIZED is the default vector 
mode. 
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Description 


Vector mode options control the way in which the debugger interacts with the 

XS 0 ???; See the Parameter descriptions for details about the SET 
v iliL/ 1 OK_MODE command. 


Related commands: 


SHOW VECTOR_MODE 
SYNCHRONIZE VECTOR_MODE 


Examples 


1. DBG> SET VECTOR_MODE SYNCHRONIZED 

This command causes the debugger to force synchronization between the 
scalar and vector processors after each vector instruction is executed. 

2 . 

DBG> SHOW VECT0R_M0DE 

Vector mode is nonsynchronized 

DBG> SET VECTOR_MODE SYNCHRONIZED O 

DBG> SHOW VECTOR_MODE 

Vector mode is synchronized 

DBG> STEP © 

stepped to .MAIN.\SUB\%LINE 99 
99: WDIVD V1,V0,V2 

DBG> STEP 0 

%SYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, 
mask=00000004, PC=000002E1, PSL=03C00010 
bre f^ 0n handled exception preceding .MAIN.\SUBULINE 100 
100: CLRL R0 

DBG> 

The comments that follow refer to the callouts in the previous example: 

O The command SET VECTOR.MODE SYNCHRONIZED causes the 
debugger to force automatic synchronization between the scalar and 
vector processors whenever a vector instruction is executed. 

® command suspends program execution on line 99, just before 

a WDIVD instruction is executed. Assume that, in this example, the 
instruction will trigger a floating-point divide-by-zero exception. 

© This STEP command executes the WDIVD instruction, which triggers 
the exception. The vector exception is delivered immediately because the 
debugger is being operated in synchronized vector mode. 
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SET WATCH 

Format 

Parameters 


Qualifiers 


Establishes a watchpoint at the location denoted by an address expression. 


SET WATCH address-expression[, ... ] [WHEN(conditional-expression)] 
[DO(command[; ...])] 


address-expression . , . 

Specifies an address expression (a program location) at which a watchpoint is 
to be set. With high-level languages, this is typically the name of a program 
variable and can include a pathname to specify the variable uniquely. More 
generally, an address expression can also be a memory address or a register 
and can be composed of numbers (offsets) and symbols, as well as one or more 
operators, operands, or delimiters. Appendix D identifies the operators that can 
be used in address expressions. 

Do not specify the asterisk (*) wildcard character. 

See Chapter 11 for information that is specific to vector registers. 

conditional-expression , . . , 

Specifies a conditional expression in the currently set language that is to be 
evaluated whenever execution reaches the watchpoint. If the expression is 
true, watch action occurs, and the debugger reports that a watchpoint has been 
triggered. If the expression is false, watch action does not occur. In this case, a 
report is not issued, the commands specified by the DO clause are not executed, 
and program execution is continued. 

Specifies a debugger command to be executed as part of the DO clause when 
watch action is taken. 


Specifies that watch action not be taken until the nth time the designated 
watchpoint is encountered (n is a decimal integer). Thereafter, the watchpoint 
occurs every time it is encountered provided that conditions in the WHEN clause 
are true. The command SET WATCH/AFTER:1 has the same effect as the SET 
WATCH command. 

Specifies that the debugger is to monitor a nonstatic variable by tracing 
instructions not only within the defining routine, but also within a routine 
that is called from the defining routine (and any other such nested calls). bEI 
WATCH/INTO enables you to monitor nonstatic variables within called routines 
more precisely than SET WATCH/OVER; but the speed of execution within called 
routines is faster with SET WATCH/OVER. 
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/OVER 

Specifies that the debugger is to monitor a nonstatic variable by tracing 
instructions oniy within the defining routine, not within a routine that is called 
y the defining routine. As a result, the debugger executes a called routine at 
normal speed and resumes tracing instructions only when execution returns to 

m-r^^ 0U L me ' SET WATCH/0VER provides faster execution than SET 
1GH/INTO; but if a called routine modifies the watched variable, execution is 
interrupted only upon returning to the defining routine. SET WATCH/OVER is 
the default behavior when you set watchpoints on nonstatic variables. 

/SILENT 

/NOSILENT (default) 

Controls whether the "watch ..." message and the source line for the current 
location are displayed at the watchpoint. The /NOSILENT qualifier specifies that 
the message is displayed. The /SILENT qualifier specifies that the message and 
source line are not displayed. The /SILENT qualifier overrides /SOURCE. 


/SOURCE (default) 
/NOSOURCE 


Controls whether the source line for the current location is displayed at the 
SOURCE qualifier specifies that the source line is displayed, 
i he /NOSOURCE qualifier specifies that the source line is not displayed. The 
/SILENT qualifier overrides /SOURCE. See also SET STEP [NOJSOURCE. 


/STATIC 

/NOSTATIC 

Enables you to override the debugger’s default determination of whether a 
specified variable (watchpoint location) is static or nonstatic. The /STATIC 
qualifier specifies that the debugger should treat the variable as a static variable 
even though it might be allocated in PI space. This causes the debugger to 
monitor the location by using the faster write-protection method rather than by 
tracing every instruction. The /NOSTATIC qualifier specifies that the debugger 
should treat the variable as a nonstatic variable, even though it might be 
allocated in PO space. The /NOSTATIC qualifier causes the debugger to monitor 

the location by tracing every instruction. Exercise caution when using these 
qualifiers. 6 


/TEMPORARY 

Causes the watchpoint to disappear after it is triggered (the watchpoint does not 
remain permanently set). 


Description 

When an instruction causes the modification of a watchpoint location the 

debugger takes the following action: 

1. Suspends program execution after that instruction has completed execution. 

2. If/AFTER was specified when the watchpoint was set, checks the AFTER 
count. If the specified number of counts has not been reached, execution 
continues and the debugger does not perform the remaining steps. 

3. Evaluates the expression in a WHEN clause, if one was specified when the 
watchpoint was set. If the value of the expression is false, execution continues 
and the debugger does not perform the remaining steps. 
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4. Reports that execution has reached the watchpoint location, unless /SILENT 
was specified ("watch of . . . ")• 

5. Reports the old (unmodified) value at the watchpoint location. 

6. Reports the new (modified) value at the watchpoint location. 

7 Displays the line of source code at which execution is suspended, unless 
/NOSOURCE or /SILENT was specified when the watchpoint was set, or fc>Ei 
STEP NOSOURCE was entered previously. 

8 Executes the commands in a DO clause, if one was specified when the 
watchpoint was set. If the DO clause contains a GO command, execution 
continues and the debugger does not perform the next step. 

9. Issues the prompt. 

For high-level language programs, the address expressions you specify mth the 
SET WATCH command are typically variable names. If you specify an abso 
memory address that is associated with a compiler-generated type, the debugger 
symbolizes the address and uses the length in bytes associated with that type 
to determine the length in bytes of the watchpoint location If you specify an 
absolute memory address that the debugger cannot associate with a compiler- 
generated type, the debugger watches 4 bytes of memory, by default, begins 
at the byte identified by the address expression. You can change this length, 
howeveTby setting thefype to either WORD (SET TYPE WORD, which changes 
the default length to 2 bytes) or BYTE (SET TYPE BYTE, wtoch friges fte 
default length to 1 byte). SET TYPE LONGWORD restores the default length of 

4 bytes. 

You can set watchpoints on aggregates (that is, entire arrays or records). A 
watchpoint set on an array or record triggers if any element of the array or 
record changes. Thus, you do not need to set watchpoints on individual array 
elements or record components. Note, however, that you cannot set an aggregate 
watchpoint on a variant record. 

You can also set a watchpoint on a record component, on an individual array 
element, or on an array slice (a range of array elements). A watehpomt set on an 
array slice triggers if any element within that slice changes. When setting the 
watchpoint, use the syntax of the current language. 

See Chapter 11 for information that is specific to vector registers. 

The following qualifiers affect what output is seen when a watchpoint is reached: 


/[NOJSILENT 

/[NO]SOURCE 

The following qualifiers affect the timing and duration of watchpoints. 

/AFTER:ra 

/TEMPORARY 

The following qualifiers apply only to nonstatic variables. 

/INTO 

/OVER 

The following qualifier is used to override the debugger’s determination of 
whether a variable is static or nonstatic: 

/[NO] STATIC 
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Static and Nonstatic Watchpoints 

The technique for setting a watchpoint depends on whether the variable is static 
or nonstatic. A static variable is associated with the same memory address 

roughout execution of the program. You can always set a watchpoint on a static 
variable throughout execution. 


A nonstatic variable is allocated on the call stack or in a register and has a value 
only when its defining routine is active (on the call stack). Therefore, you can set 
a watchpoint on a nonstatic variable only when execution is currently suspended 
withm the scope of the defining routine (including any routine called by the 

efinining routine). The watchpoint is canceled when execution returns from the 
defining routine. 


Another distinction between static and nonstatic watchpoints is speed of 
execution. To watch a static variable, the debugger write-protects the page 
containing the variable. If your program attempts to write to that page, an access 
violation occurs and the debugger handles the exception, determining whether the 
watched variable was modified. Except when writing to that page, the program 
executes at normal speed. 8 

To watch a nonstatic variable, the debugger traces every instruction in the 
variables defining routine and checks the value of the variable after each 
^T 1 ? 1011 has been executed. Since this significantly slows down execution, 
the debugger issues a message when you set a nonstatic watchpoint. 

As explained in the next paragraphs, the /[NOJSTATIC and /INTO and /OVER 
qualifiers enable you to exercise some control over speed of execution and other 
lactors when watching variables. 

The debugger determines whether a variable is static or nonstatic by checking 
how it is allocated. Typically, a static variable is in PO space (0 to 3FFFFFFF, 
hexadecimal); a nonstatic variable is in PI space (40000000 to 7FFFFFFF) or 
in a register. The debugger issues a warning if you try to set a watchpoint on 
a variable that is allocated in PI space or in a register when execution is not 
currently suspended within the scope of the defining routine. 

The /[NOJSTATIC qualifiers enable you to override this default behavior. For 
example, if you have allocated nonstack storage in PI space, use the /STATIC 
qualifier when setting a watchpoint on a variable that is allocated in that storage 
area This enaWes the debugger to use the faster write-protection method of 
watching the location instead of tracing every instruction. Conversely, if, for 
example, you have allocated your own call stack in P0 space, use the /NOSTATIC 
qualifier when setting a watchpoint on a variable that is allocated on that 
call stack. This enables the debugger to treat the watchpoint as a nonstatic 


You can also control the execution speed for nonstatic watchpoints in called 
routines by means of the /INTO and /OVER qualifiers. 


Global Section Watchpoints 

You can set watchpoints on variables or arbitrary program locations in global 
sections. A global section is a region of memory that is shared among all 
processes of a multiprocess program. A watchpoint that is set on a location in a 
global section (a global section watchpoint) triggers when any process modifies 
the contents of that location. 
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You set a global section watchpoint just as you would set a 
variable However, because of the way the debugger monitors global section 
watehpoints! note ihe following point. When setting watchpoints on arrays or 
records, performance is improved if you specify individual elements rather than 
the entire structure with the SET WATCH command. 

If you set a watchpoint on a location that is not yet ma PP ed + to ^ glob ^ 
the watchpoint is treated as a conventional static watchpoint. When Relocation 
is subsequently mapped to a global section, the watchpoint is automatically 
treated as a global section watchpoint and an informational message is issued. 
?he watchpofnt is then visible from each process of the multiprocess program. 

Related commands: 


SET BREAK 

SET STEP [NOjSOURCE 

SET TRACE 

(SHOW,CANCEL) WATCH 

Examples 

1. DBG> SET WATCH MAXCOUNT 

This command establishes a watchpoint on the variable MAXCOUNT. 

2. DBG> SET WATCH ARR 
DBG> GO 


watch of SUBR\ARR at SUBR\%LINE 12+8 
old value: 

7 

12 
3 


( 1 ) 

( 2 ) 

(3) 

new value: 
( 1 ) 

( 2 ) 

(3) 


7 

12 

28 


break at SUBRULINE 14 
DBG> 

In this example, the SET WATCH command sets a watchpoint on the 
three-element integer array, ARR. Execution is then resumed with the GO 
command. The watchpoint triggers whenever any array element changes, in 
this case the third element changed. 

3. DBG> SET WATCH ARR (3) 

In this example, the SET WATCH command sets a watchpoint on element 3 
of array ARR (FORTRAN array syntax). The watchpoint triggers whenever 

element 3 changes. 

4. DBG> SET WATCH P_ARR[3:5] 

In this example, the SET WATCH command sets a watchpoint on the array 
slice consisting of elements 3 to 5 of array P_ARR (Pascal array syntax). The 
watchpoint triggers whenever any of these elements change. 
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5. DBG> SET TRACE/SILENT SUB2 DO (SET WATCH 


K) 


In this example, variable K is a nonstatic variable and is defined only when 
its defining routine, SUB2, is active (on the call stack). The SET TRACE 
command sets a tracepoint on SUB2. When the tracepoint is triggered during 
execution, the DO clause sets a watchpoint on K. The watchpoint is then 

Jp!nT ti0n retU T nS fr0m routine SUB2 ' ^ /SILENT qualifier 
on the SET TRACE command suppresses the "trace ...» message and the 
display of source code at the tracepoint. 


6 . 


DBG_1> SET WATCH ARR(l) 

DBG_1> SHOW WATCH 
watchpoint of PPL3\ARR(1) 

DBG_1> GO 

%DEBUG-I-WATVARNOWGBL, watched variable PPL3\ARR(1) has been remapped 
to a global section w 

5 raCe ° n act f vation at routine PPL3 in IPROCESS NUMBER 2 

predefined trace on activation at routine PPL3 in %PROCESS NUMBER 3 

WatC i!o 0f PPL3 \ ARR d) at PPL3\%LINE 93 in IPROCESS NUMBER 2 
93: ARR(l) = INDEX 

old value: 0 
new value: 1 

break at PPL3\ILINE 94 in IPROCESS NUMBER 2 

94: ARR(I) = I 

DBG_2> DO (SHOW WATCH) 


For %PROCESS_NUMBER 1 
watchpoint of PPL3\ARR(1) 
For %PROCESS_NUMBER 2 
watchpoint of PPL3\ARR(1) 
For %PROCESS_NUMBER 3 
watchpoint of PPL3\ARR(1) 
DBG 2> 


[global-section watchpoint] 
[global-section watchpoint] 
[global-section watchpoint] 


In this example of a global section watchpoint, the SET WATCH command 
sets a watchpoint on element 1 of array ARR. Because ARR has not yet 
been mapped to a global section, the SHOW WATCH command identifies the 
watchpoint as a conventional static watchpoint. 


Mt f r the J?° comman d resumes execution, ARR is remapped to a global 
section. The watchpoint is automatically treated as a global section 
watchpoint. 


Processes 2 and 3 come under debugger control, then the watchpoint is 
m process 2 > interru pting execution. At this point, the SHOW 
WATCH command confirms that the watchpoint is visible from each process. 
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SET WINDOW 

Creates a screen window definition. 

Format 

SET WINDOW window-name AT (start-line,line-count[, start-col,col-count]) 


Parameters 


window-name 

Specifies the name of the window you are 
that name already exists, it is canceled in 


defining If a window definition with 
favor of the new definition. 


IpSs the starting line number of the window This line displays the window 
title, or header line. The top line of the screen is line . 


Specifies the number of text lines in the window, not counting the header line. 
The value must be at least 1. The sum of start-line and line-count must not 
exceed the current screen height. 


iSel the starting column number of the window. This is the column at which 
the first character of the window is displayed. The leftmost column of the screen 

is column 1. 


Spedfiesthe number of characters per line in the window. The value must be at 
least 1. The sum of start-col and col-count must not exceed the current screen 

width. 


Description 


screen window is a rectangular region on the terminal screen through which 
ou can view a display. The SET WINDOW command establishes a window 
efinition by associating a window name with a screen region. You specify the 
2 reen region in terms of a starting line and height (line count) and, optionally, 
starting column and width (column count). If you do not specify the sta ing 
--and minmn count, thev default to column 1 and the current screen widti 


You can specify a window region in terms of expressions that use the built-in 
symbols %PAGE and % WIDTH. 

You can use the names of any windows you have defined with the SET WINDOW 
command in a DISPLAY command to position displays on the screen. 


Window definitions are dynamic-that is, window dimensions expand and 
contract proportionally when a SET TERMINAL command changes the screen 


width or height. 
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Related commands: 

DISPLAY 

(SET,SHOW,CANCEL) DISPLAY 
(SET,SHOW) TERMINAL 
(SHOW,CANCEL) WINDOW 


Examples 

1. DBG> SET WINDOW ONELINE AT (1,1) 

This command defines a window named ONELINE at the top of the screen. 
The window is one line deep and, by default, spans the width of the screen. 

2. DBG> SET WINDOW MIDDLE AT (9,4,30,20) 

This command defines a window named MIDDLE at the middle of the screen 
The window is 4 lines deep starting at line 9, and 20 columns wide starting 
at column 30. 


3. DBG> SET WINDOW FLEX AT (%PAGE/4,IPAGE/2,IWIDTH/4,%WIDTH/2) 

This command defines a window named FLEX that occupies a region around 

le ° f the screen and is defined in terms of the current screen height 
(%PAGE) and width (%WIDTH). 
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SHOW ABORT_KEY 

Identifies the Ctrl-key sequence currently defined to abort the execution of a 
debugger command or to interrupt program execution. 


Format 

SHOW ABORTJCEY 


Description 


By default, the Ctrl/C sequence, when entered within a debugging session, aborts 
the execution of a debugger command and interrupts program execution The 
SET ABORT_KEY command enables you to assign the abort function to anot 
Ctrl-key sequence. The SHOW ABORTJKEY command identifies the Ctrl-key 
sequence currently in effect for the abort function. 

Related commands: 


Example 


Ctrl/C 

SET ABORTJKEY. 


DBG> SHOW ABORTJCEY 
Abort Command Key is CTRL_C 
DBG> SET ABORTJCEY = CTRL_P 
DBG> SHOW ABORTJCEY 
Abort Command Key is CTRL_P 
DBG> 

The first SHOW ABORTJKEY command identifies the default abort command 
key sequence, Ctrl/C. The command SET ABORTJCEY = CTRL P assi ^ s ^® 
abort-command function to the Ctrl/P sequence, as verified by the second SHOW 

ABORT_KEY command. 
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SHOW AST 


Indicates whether delivery of ASTs is enabled or disabled. 

Format 

SHOW AST 


Description 

The SHOW AST command indicates whether delivery of ASTs is enabled or 
disabled. The command does not identify an AST whose delivery is pending. The 
delivery of ASTs is enabled by default and with the ENABLE AST command The 
delivery of ASTs is disabled with the DISABLE AST command. 

Related commands: (ENABLE,DISABLE) AST. 


Example 


DBG> SHOW AST 
ASTs are enabled 
DBG> DISABLE AST 
DBG> SHOW AST 
ASTs are disabled 
DBG> 

The SHOW AST command indicates whether the delivery of ASTs is enabled. 
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SHOW ATSIGN 


Identifies the default file specification established with the last SET ATSIGN 
command. The debugger uses this file specification when processing the 
(Execute Procedure) command. 


Format 

SHOW ATSIGN 

Description 

Related commands: 

@ (Execute Procedure) 
SET ATSIGN 


Examples 


1 DBG> SHOW ATSIGN , 

‘ No indirect command file default in effect, using DEBUG.COM 

DBG> 

This example shows that, if the SET ATSIGN command was not used, 
command procedures are assumed to have the default file specification 
SYS$DISK:[ ]DEBUG.COM. 

2 DBG> SET ATSIGN USER:[JONES.DEBUG].DBG 

DBG> SHOW ATSIGN 

Indirect command file default is USER:[JONES.DEBUG].DBG 
DBG> 

In this example, the SHOW ATSIGN command indicates the default file 
specification for command procedures, as previously established with the bl^l 

ATSIGN command. 
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SHOW BREAK 


Format 


Qualifiers 


Displays information about breakpoints. 
SHOW BREAK 


/PREDEFINED 

Displays information about predefined breakpoints. 

/USER 

Displays information about user defined breakpoints. 


Description 


The SHOW BREAK command displays information about breakpoints that are 
currently set, including any options such as WHEN or DO clauses, /AFTER 
counts, and so on. 


By default, SHOW BREAK displays information about both user defined and 
r”" b r T S POintS (if any) ' This is equivalent to entering the command 
W BREAK/USER/PREDEFINED. User defined breakpoints are set with the 
SE1 BREAK command. Predefined breakpoints are set automatically when you 
invoke the debugger, and they depend on the type of program you are debugging. 


SeeSe^on 9.3.2 for information about predefined breakpoints that are associated 
with Ada tasking exception events. 


i f J^ T ^ Stablished a break P° int usi ng the /AFTERrra qualifier with the SET 
BREAK command, the SHOW BREAK command displays the current value of 
the decimal integer n, that is, the originally specified integer value minus one for 
each time the breakpoint location was reached. (The debugger decrements n each 
time the breakpoint location is reached until the value of n is zero, at which time 
the debugger takes break action.) 


Related commands: (SET,CANCEL) BREAK. 


Examples 


1. DBG> SHOW BREAK 

breakpoint at SUB1\L00P 
breakpoint at MAIN\MAIN+1F 

do (EX SUB1\D ; EX/SYMBOLIC PSL; GO) 
breakpoint at routine SUB2\SUB2 
/after: 2 
DBG> 

BREAK command identifies all breakpoints that are currently 
se . This example indicates user defined breakpoints that are triggered 
whenever execution reaches SUB1XLOOP, MAINXMAIN, and SUB2XSUB2 
respectively. ’ 
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DBG> show break/predefined nOTmT .„, 

predefined breakpoint on Ada event "DEPENDENTS_EXCEPTION 

predefined breakpoint on Ada event "EXCEPTION_TERMINATED" 
for any value 
DBG> 

This command identifies the predefined breakpoints that are currently set. 
The example shows two predefined breakpoints, which are associated mtii 
Ada tasking exception events. These breakpoints are set automatically by the 
debugger for all Ada programs and for any mixed language program that is 
linked with an Ada module. 
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SHOW CALLS 


Identifies the currently active routine calls (the call stack). 


Format 

SHOW CALLS [integer] 


Parameters 

integer 

A decimal integer that specifies the number of call frames to be identified. By 
default, all currently active call frames are identified. 

Description 

Whenever a call is made to a routine as your program executes, the VMS 
operating system creates a separate call frame on the call stack. Each call frame 
stores information about the calling routine. The call frame for the most recently 
called routine is on the top of the call stack. 

When a routine returns execution to its caller, the call frame for that routine is 
removed from the call stack. 

The SHOW CALLS command shows a traceback that lists the sequence of active 
routine calls that lead to the routine in which execution is currently suspended. 
Any recursive routine calls are shown in the display, so you can use the SHOW 
CALLS command to examine the chain of recursion. 

One line of information is displayed for each call frame, starting with the most 
recent call. The top line identifies the currently executing routine, the next line 
identifies its caller, the following line identifies the caller of the caller, and so on. 

The following information is provided for each call frame: 

• The name of the enclosing module. An asterisk (*) to the left of a module 
name indicates that the module is set. 

• The name of the calling routine, provided the module is set (the first line 
shows the currently executing routine). 

• The line number where the call was made in that routine, provided the 
module is set (the first line shows the line number at which execution is 
suspended). 

• The value of the PC in the calling routine at the time that control was 
transferred to the called routine. The PC value is shown as a memory 
address relative to the address of the name of the routine and also as an 
absolute address. 

Even if your program contains no routine calls, the SHOW CALLS command 
displays an active call. The reason for this is that your program has a stack 
frame built for it when it is first activated. Thus, if the SHOW CALLS display 
shows no active calls, either your program has terminated or the call stack has 
been corrupted. 
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SHOW CALLS 


Example 


Related commands: 

SHOW SCOPE 
SHOW STACK 


DBG> SHOW CALLS 

module name routine name 


SUB2 

*SUB1 

*MAIN 

DBG> 


SUB2 

SUB1 

MAIN 


line 

5 

10 


rel PC 

00000002 

00000014 

0000002C 


abs PC 

0000085A 

00000854 

0000082C) 


This command displays information about the sequence of currently active 


procedure calls. 


CD-210 




Debugger Command Dictionary 
SHOW DEFINE 


SHOW DEFINE 


Format 


Identifies the default qualifier (/ADDRESS, /COMMAND 
/VALUE) currently in effect for the DEFINE command. 


/PROCESS_GROUP, or 


SHOW DEFINE 


Description 


Example 


The default qualifier for the DEFINE command 
established with the SET DEFINE command. If 
entered, the default qualifier is /ADDRESS. 


is the default qualifier last 
no SET DEFINE command 


was 


To identify a symbol defined with the DEFINE 
SYMBOL/DEFINED command. 


command, use the SHOW 


Related commands: 

DEFINE 

DEFINE/PROCESS_GROUP 

DELETE 

SET DEFINE 

SHOW SYMBOL/DEFINED 


DBG> SHOW DEFINE 

Current setting is: DEFINE/ADDRESS 
DBG> 


The SHOW DEFINE command indicates that the DEFINE 
definition by address. 


command is set for 
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SHOW DISPLAY 


SHOW DISPLAY 

Identifies one or more existing screen displays. 


Format 


Qualifiers 


SHOW DISPLAY [display-name[, ... ]] 


Parameters 


Shin a display name. Do not specify a display name wrth /ALL. 


use 


Lists all display definitions. Do not specify a display name with /ALL. 

/SUFFIX[=process-identifier-type] rmr<fcPi?orFSS has the 

Applies to a multiprocess debugging configuration (when DBG$PROCESs h as 
value MULTIPROCESS). Use this qualifier only directly after a display name. 

Appends a process-identifying suffix to a display 

visible process at the time the command was issued. This qualifier is usea 
primarily in command procedures when specifying display definitions or key 
definitions that are bound to display definitions. 

Use any of the following process-identifier-type keywords. 

PROCESS_NAME The display-name suffix is the VMS process name. 

PROCESS NUMBER The display-name suffix is the process number (as shown 

in a SHOW PROCESS display). 

PROCESS_PID The display-name suffix is the VMS process 

identification number (PID). 

If vou specify /SUFFIX without a process-identifier-type keyword, the P roces ® 
denttfto^e used for the display-name suffix is, by default, the same as that 
used for the prompt suffix (see SET PROMPT/SUFFIX). 


Description 


The SHOW DISPLAY command lists all displays according to their order in the 
display Ust. The most hidden display is listed first, and the dtsplay that ts on top 
of the display pasteboard is listed last. 

For each display, the SHOW DISPLAY command lists its name maximum size, 
screen window and display kind (including any debug command list). It also 
identifies whether the display is removed from the pasteboard or is dynamic ( 
dynamS aS automatically adjusts its window dimensions if the screen sue ts 
changed with the SET TERMINAL command). 
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SHOW DISPLAY 


Example 


Related commands: 

DISPLAY 

EXTRACT/SCREEN.LAYOUT 
(SET,CANCEL) DISPLAY 
(SET,CANCEL,SHOW) WINDOW 
SHOW SELECT 


udkjs onuw uioriiHl 


display SRC at HI, size = 64, dynamic 

kind - SOURCE (EXAMINE/SOURCE .%SOURCE SCOPE\%PC) 
display INST at HI, size = 64, removed, dynamic 
kind = INSTRUCTION (EXAMINE/INSTRUCTION .0\%PC) 

disDlav ODT at SiZ6 = fnn removed ' d y namic ' kind = REGISTER 

isplay OUT at S45, size = 100, dynamic, kind = OUTPUT 

display EXSUM at Q3, size = 64, dynamic, kind = DO (EXAMINE SUM) 

Display PROMPT at S6, size = 64, dynamic, kind = PROGRAM 

DISP f^ Y ™ I T and lists a11 displays currently defined. In this 

PT?nSfef hey i^ 1Ude h ! P redefined displays (SRC, INST, REG, OUT, and 
ROMPT), and the user-defined DO display EXSUM. Displays INST and REG 

fnoXTl 7 £ display pasteboard: the DISPLAY command must be used 
in order to display them on the screen. 


CD-213 










Debugger Command Dictionary 
SHOW EDITOR 


SHOW EDITOR 

Indicates the action taken by the EDIT command, as established by the SET 
EDITOR command. 


Format 

SHOW EDITOR 


Description 


Examples 


Related commands: 
EDIT 

SET EDITOR 


1 dbg> show editor 

The editor is SPAWNed, with command line 
"LSEDIT/START_POSITION=(n,1)" 

DBG> 

This command indicates that, when you enter the BUT command, you spawn 
the VAX Language-Sensitive Editor in a subprocess. The /START.POblllUW 
Qualifier that is appended to the command line indicates that the editing 
cursor is initially positioned at the beginning of the line that is centered m 
the debugger’s current source display. 

2. DBG> SET EDITOR/CALLABLE_TPU 

DBG> SHOW EDITOR , 

The editor is CALLABLE_TPU, with command line TPU 

DBG> 

In this example, the SHOW EDITOR 

enter the EDIT command, you invoke the callable version ofthe VAX iext 
Processing Utility (VAXTPU). The editing cursor is initially positioned at the 

beginning of source line 1. 
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SHOW EVENTFACILITY 


SHOW EVENT_FACILITY 


Identifies the current event facility and the associated event names. 


Event facilities are available for programs that call Ada 
use DECthreads services. 


or SCAN routines or that 


Format 


SHOW EVENT_FACILITY 


Description 


Example 


The current event facility (ADA, THREADS, or SCAN) defines the eventpoints 
that you can set with the SET BREAK/EVENT and SET TRACE/EVENT 
commands. 

^FACILITY command identifies the event names associated 
with the current event facility. These are the keywords that you can sDecifv 

c“df T ’ CANCEL) BREAK/EVENT and (SET,CANCEL) TRACE/EVENT 

Related commands: 

(SET,CANCEL) BREAK/EVENT 
SET EVENT.FACILITY 
(SET,CANCEL) TRACE/EVENT 
SHOW BREAK 
SHOW TASK 
SHOW TRACE 


DBG> SHOW EVENT_FACILITY 
event facility is THREADS 


Tins command identifies the current event facility to be THREADS DECthreads 

be used ** a SET BREAK 
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SHOW EXIT_HANDLERS 


SHOW EXIT_HANDLERS 

Identifies the exit handlers that have been declared in your program. 

Format 

SHOW EXIT_HANDLERS 


Description 


The exit handler routines are displayed in the order that they are catted (that 
is last in first out). The routine name is displayed symbolically, if possible. 
Otherwise, its address is displayed. The debugger’s exit handlers are not 

displayed. 


Example 

DBG> SHOW EXIT_HANDLERS 
exit handler at S TACKS\CLEANUP 

DBG> , , 

This command identifies the exit handler routine CLEANUP, which is declared in 

module STACKS. 
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SHOW IMAGE 


SHOW IMAGE 


Format 


Parameters 


°“ ° r ^ ima S es that « ^ 


SHOW IMAGE [image-name] 


Description 


image-name 

Specifies the name of a shareable image to be included in the display. If you do 
not specify a name, or if you specify the asterisk (*) wildcard character bv itself 
all images are listed. You can use - within an image name. Y ’ 


Example 


The SHOW IMAGE command displays the following information: 

• Name of the shareable image 

• Start and end addresses of the image 

the RST) ^ image haS been S6t With the SET IMAGE command (loaded into 

Current image that is your debugging context (marked with an asterisk (*)) 

• Total number of images selected in the display 

• Number of bytes allocated for the RST and other internal structures 
Related commands: 

(SET,CANCEL) IMAGE 
(SET,SHOW,CANCEL) MODULE 


DBG> SHOW IMAGE SHARE* 
image name 

*SHARE 
SHARE1 
SHARE2 
SHARE3 
SHARE4 

total images: 5 
DBG> 

an of the shareable images whose names 
j QTT a ottio ^ which are associated with the program Imag’es SHARF 

and SHARE2 are set. The asterisk (*) identffles SHAKE as th^Sme^ 


set 

base address 

end address 

yes 

00000200 

00000FFF 

no 

00001000 

000017FF 

yes 

00018C00 

000191FF 

no 

00019200 

000195FF 

no 

00019600 

0001B7FF 

bytes 

allocated: 33032 
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SHOW KEY 


SHOW KEY 


Displays the debugger predefined key definitions and those created by the 
DEFINE/KEY command. 


Format 


SHOW KEY [key-name] 


Parameters 


Key Name 

PF1 

PF2 

PF3 

PF4 

KP0-KP9 

PERIOD 

COMMA 

MINUS 

ENTER 

El 

E2 

E3 

E4 

E5 

E6 

HELP 

DO 

F6-F20 


with /ALL. Valid key names are as follows. 


LK201 Keyboard 

PF1 
PF2 
PF3 
PF4 

Keypad 0—9 
Keypad period (.) 
Keypad comma (,) 
Keypad minus (-) 
ENTER 
Find 

Insert Here 

Remove 

Select 

Prev Screen 
Next Screen 
Help 
Do 

F6-F20 


VT100-Type 

PF1 

VT52-Type 

Blue 

PF2 

Red 

PF3 

Black 

PF4 

Keypad 0-9 

Keypad 0-9 

Keypad period (.) 
Keypad comma (,) 
Keypad minus (—) 
ENTER 

ENTER 


Qualifiers 


Displays all key definitions for the cnrrent state, by default, or for the states 
specified with the /STATE qualifier. Do not specify a key name with / . 

SXs only the key definitions (by default, all the fitters associated with a 
key definition are also shown, including any specified state). 

Dispfays^he names of all the states for which keys have been defined. Do not 
specify other qualifiers with /DIRECTORY. 
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SHOW KEY 


Description 


/bTATE=(state-name 
/NOSTATE (default) 

Selects one or more states for which a key definition is displayed. The /STATE 
qualifier displays key definitions for the specified states. You can specify 

AsJte n name y 38 DEFAULT and GOLD, or user-defined states. 

A state name can be any appropriate alphanumeric string. The /NOSTATE 

qualifier displays key definitions for the current state only 


Keypad mode must be enabled (SET MODE KEYPAD) before 
command. Keypad mode is enabled by default. 


you can use this 


By default the current key state is the "DEFAULT" state. The current state can 
be changed with the SET KEY/STATE command, or by pressing a key that causes 

/STATF Cha ^fi ^ key , that was defined with the DEFINE/KEY/LOCK_STATE 
/oIAlE qualifier combination). 


Related commands: 


DEFINE/KEY 
DELETE/KEY 
SET KEY 


Examples 


1. DBG> SHOW KEY/ALL 

This command displays all the key definitions for the current state. 


2. DBG> SHOW KEY/STATE=BLUE KP8 
GOLD keypad definitions: 

^ = " Scr °U/Top" (noecho,terminate,nolock) 

DBG> 


This command displays the definition for keypad key 8 in the BLUE state. 

3. DBG> SHOW KEY/BRIEF KP8 
DEFAULT keypad definitions: 

KP8 = "Scroll/Up" 

DBG> 


This command displays the definition for keypad key 8 in the current key 


4. DBG> SHOW KEY/DIRECTORY 
MOVE_GOLD 
M0VE_BLUE 
MOVE 
GOLD 

EXPAND_GOLD 

EXPAND_BLUE 

EXPAND 

DEFAULT 

CONTRACT_GOLD 

CONTRACT_BLUE 

CONTRACT 

BLUE) 

DBG> 

C T mand dispIays the names of the states for which keys have been 
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SHOW LANGUAGE 


SHOW LANGUAGE 

Identifies the current language. 

Format 

SHOW LANGUAGE 


Description 


The current language is the language last established with the SET LANGUAGE 
command. If no SET LANGUAGE command was entered, the current a gu g 
is, by default, the language of the module containing the mam program. 

Related command: SET LANGUAGE. 


Example 


DBG> SHOW LANGUAGE 
language: BASIC 
DBG> 

This command displays 


the name of the current language as BASIC. 
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Debugger Command Dictionary 

SHOW LOG 


Format 

Description 

Examples 


lofffile^ eS Whether the debugger is writin S t0 a log file and identifies the current 


SHOW LOG 


ff’no'sET 11 ! or file ‘ S ^ '° g “ e laSt established by a SET LOG command. 

iZSSS'*«££* 0,6 currentlog flle is *• 

Related commands: 


SET LOG 

SET OUTPUT [NOJLOG 

SET OUTPUT [NO]SCREEN_LOG 


1. DBG> SHOW LOG 

not logging to DEBUG.LOG 
DBG> 


Sf, displays the name of the current log file as DEBUG.LOG (the 

default log file) and reports that the debugger is not writing to it. 


DBG> SET LOG PR0G4 
DBG> SET OUTPUT LOG 
DBG> SHOW LOG 

logging to USER$:[JONES.WORK]PR0G4.LOG 


is n pROG4 a LOr e, r th tif ET L0G C ff mand establishes that the current log file 
ULr4.LOG (in the current default directory). The SET OUTPUT I OP 

Th“ SHOwTor the debugger *° log debugger input and output into that file. 

file PROG4 POM C0 "V nand confi ™ s that the debugger is writing to the log 
me PKOG4.COM in the current default directory. 
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SHOW MARGINS 



SHOW MARGINS 


Identifies the current source-line margin settings 


for the display of source code. 


Format 

SHOW MARGINS 


Description 


The current margin settings are the margin settings last established with_ the 
SET MARGINS command. If no SET MARGINS command was entered, 
margin is set to 1 and the right margin is set to 255 by default. 

Related command: SET MARGINS. 


Examples 

1. DBG> SHOW MARGINS 

left margin: 1 , right margin: 255 

DBG> 

This command displays the default margin settings of 1 and 255. 

2 DBG> SET MARGINS 50 
DBG> SHOW MARGINS 

left margin: 1 , right margin: 50 

DBG> 

This command displays the default left margin setting of 1 and the modifie 
right margin setting of 50. 

3 DBG> SET MARGINS 10:60 
DBG> SHOW MARGINS 

left margin: 10 , right margin: 60 
DBG> 

This command displays both margin settings modified to 10 and 60. 
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SHOW MAX_SOURCE_FILES 


Identifies the maximum number of source files that the 
at any one time. 


debugger can keep open 


Format 


SHOW MAX_S0URCE_F1LES 


Description 


The maximum number of source files that the debugger can keep open at anv one 

MAx's0UTiC P E eC1 pn d f? inS th<> S / T M^SOURCE.FILES command. If no SET 
by default CJL command waB entere<1 . «>e maximum number of flies is 5 


Related commands: 

SET MAX_SOURCE_FILES 
(SET,SHOW,CANCEL) SOURCE 


Example 


DBG> SHOW MAX_SOURCE_FILES 
max_source files: 7 
DBG> 


This command shows that the debugger 
open at any one time. 


can keep a maximum of 7 source files 
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SHOW MODE 


SHOW MODE 


Identifies the current debugger modes (screen or no screen, keypad or nokeypad, 
and so on) and the current radix. 


Format 

SHOW MODE 


Description 


The current debugger modes are the modes last established with the SET MODE 

command. If no SET MODE command was entered, the current modes a , y 

default: 


DYNAMIC 

NOG_FLOAT (D_float) 

INTERRUPT 

KEYPAD 

LINE 

NOSCREEN 

SCROLL 

NOSEPARATE 

SYMBOLIC 


Related commands: 

(SET,CANCEL) MODE 
(SET,SHOW,CANCEL) RADIX 


Example 


dbg> show MODE . j 

modes: symbolic, line, d_float, screen, scroll, keypad, 
dynamic, interrupt, no separate window 
input radix :decimal 
output radix-.decimal 


The SHOW MODE command displays the current modes 
output radix. 


and current input and 
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SHOW MODULE 


SHOW MODULE 


Format 


Parameters 


Displays information about the modules in the current image. 


SHOW MODULE [module-name] 


module-name 

Specifies the name of a module to be included in the display. If you do not specify 
a name or if you specify the asterisk (*) wildcard character by itself, all modules 

are listed. You can use * within a module name. Shareable image modules are 
selected only if the /SHARE qualifier is specified modules are 


Qualifiers 


/RELATED 

/NORELATED (default) 

Applies to Ada programs. 

Oontrols whether the debugger includes, in the SHOW MODULE display any 
relationship ** ^ ^ t0 & specified module through a with-clause or subunit 

SHOW MODULE/RELATED displays related modules as well as those specified. 

he display identifies the exact relationship. By default (/NORELATED) no 
related modules are selected for display (only the modules specified are selected). 

/SHARE 

/NOSHARE (default) 

Controls whether the debugger includes, in the SHOW MODULE display 

SS Th 168 have beenbnked with y° ur program. By default 
(/JNUbHARE) no shareable image modules are selected for display. 

The debugger creates dummy modules for each shareable image in your program 

SHOW MOnTTTF/qwAP?^ 16 T® 8 ® modules " have the prefix "SHARES"^ 
fh^^ M i° DUL + ? /SHARE ldentlfies these shareable image modules, as well as 
the modules in the current image. ’ 

Setting a shareable image module loads the universal symbols for that image 
into the run-time symbol table so that you can reference these symbols fronf the 
urrent image. However, you cannot reference other (local or global) symbols in 

SET I^^GE^ml^HOW^IMAGE^commmM^ 111 ^ 6 ^ ** — 


Description 


Note 


UtaS!? im tt ge iS either the main image (by default ) or the image 
established as the current image by a previous SET IMAGE command. 
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SHOW MODULE 


The SHOW MODULE command displays the following information about one or 
more modules selected for display: 

• Name of the module. 

. Programming language in which the module is coded, unless all modules are 
coded in the same language. 

. Whether the module has been set with the SET M ° DUL f “”V”“ d th ^ at 
is, whether the symbol records of the module have been loaded into the 

debugger’s run-time symbol table (RST). 

. Space (in bytes) required in the RST for symbol records in that module. 

• Total number of modules selected in the display. 

. Number of bytes allocated for the RST and other internal structures (the 
amount of heap space in use in the main debugger s process). 

See Section E.l.14.1 for information specific to Ada programs. 

Related commands: 

(SET,SHOW,CANCEL) IMAGE 
SET MODE [NO]DYNAMIC 
(SET,CANCEL) MODULE 
(SET,SHOW,CANCEL) SCOPE 
SHOW SYMBOL 


Examples 


symbols size 


yes 

no 


432 

280 


2. bytes allocated: 2740. 


1. DBG> SHOW MODULE 
module name 

TEST 

SCREEN_I0 

total PASCAL modules: 

DBG> 

Tn +Vtic Avamnle the SHOW MODULE command, without a parameter 
spewed dSpfcs WoSration about all of the modules in ttie current _ = e, 
which is the main image by default. This example shows ^ 

when all modules have the same source.language. 

shows that module TEST has been set, but module SCREEN JO has not. 

2 DBG> SHOW MODULE FOO, MAIN,SUB* 

symbols 


yes 

no 

no 

no 


language 

size 

MACRO 

432 

FORTRAN 

280 

FORTRAN 

164 

FORTRAN 

204 


module name 

FOO 
MAIN 
SUB1 
SUB2 

total modules 
DBG> 

In this example, the SHOW MODULE command displays information about 
the modules FOO and MAIN, and all modules having the prefix SUB. Thi 
exampleshows the display format when the modules do not have the same 

source language. 


bytes allocated: 60720. 
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SHOW MODULE 


DBG> SHOW MODULE/SHARE 
module name 

F00 
MAIN 


SHARE$DEBUG 

SHARE$LIBRTL 

SHARE$MTHRTL 

SHARE$SHARE1 

SHARE$SHARE2 

total modules: 17. 


symbols 

language 

size 

yes 

MACRO 

432 

no 

FORTRAN 

280 

no 

Image 

0 

no 

Image 

0 

no 

Image 

0 

no 

Image 

0 

no 

Image 

0 

bytes allocated: 162280. 


DBG> SHOW SYMBOL * IN SHARE$SHARE2 
DBG> 

In ttda example, the SHOW MODULE/SHARE command identifies all 

raodul ““ H , le “7“' image and all of the shareable images 
( He names of the shareable images are prefixed with "SHARES") The 

SetS the Shareable ima ^ e 

SHARE$SHARE2. The SHOW SYMBOL command identifies any universal 
symbols defined in the shareable image SHARE2. 
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SHOW OUTPUT 


SHOW OUTPUT 

Identifies the current output options. 


Format 


SHOW OUTPUT 


Description 


The current output options are the options last established with the SET 


Related commands: 

SET LOG 

SET MODE SCREEN 
SET OUTPUT 

Example 


dbg> show output 

noverifV/ terminal/ screen_log* 

logging to USER$:[JONES.WORK]DEBUG.LOG;9 


This command shows the following current output options: 

. Debugger commands read from debugger command procedures are not echoed 
on the terminal. 

• Debugger output is being displayed on the terminal. 

• The debugging session is being logged to the log file 

USER$:[JONES.WORK]DEBUG.LOG;9. 

. The screen contents are logged as they are updated in screen mode. 
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SHOW PROCESS 


SHOW PROCESS 


Format 


Parameters 


lnf T at T ab0Ut P rocesses that are currently under debugger control 

DBGrPR^ d SsTiX S SttffE& C ° nfigUra,i0n <WhCa 


SHOW PROCESS [process-spec[, ... ]] 


process-spec 

Specifies a process. Use any of the following forms: 
[%PROCESS_NAME] process-name 


[%PROCESS_NAME] "process-name 

%PROCESS_PID processed 

%PROCESS_NUMBER proc-number 
(or %PROC proc-number) 

process-group-name 

%NEXT_PROCESS 

%PREVIOUS_PROCESS 

%VISIBLE_PROCESS 


The VMS process name, if that 
name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 

The VMS process name, if that name 
contains space or lowercase characters. 
You can also use apostrophes (') instead 
of quotation marks ("). 

The VMS process identification number 
(PID, a hexadecimal number). 

The number assigned to a process 
when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 

A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. Do not 
specify a recursive symbol definition. 

The process after the visible process in 
the debugger’s circular process list. 

The process previous to the visible 
process in the debugger’s circular 
process list. 

The process whose call stack, register 
set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


You can also use the asterisk (*) wildcard character to specify all processes. 
/ALL ° n ° SpeClfy 3 pr0Cess ’ the visible Process is selected, unless you specify 


Qualifiers 


/ALL 

SX”* ta0W ” to ‘ he debuBger f0r ^ ■>»» specify a process 
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SHOW PROCESS 


msptays only one line of information for each process selected for display. The 
/BRIEF qualifier is the default. 

Shows whether dynamic processi setting th^command^^TPROCESS 

setting is enabled by default and is controlled with the command & 

/[NOIDYNAMIC. 

Do not specify a process with /DYNAMIC. Do not specify /ALL, /BRIEF, /FUL , 
/[NO]HOLD, or /VISIBLE with /DYNAMIC. 

Displays maximum information for each process selected for display. 

/HOLD 

Selects^either processes that are on hold, or processes that are not on hold for 
display. f 

hold^f 

are not on hold. . 

T „ e , .1. /ttot n and /NOHOLD on the same command line, the effect is 

SI" S me on hXnd processes that are not on hold for display 
SietfalSrspecihed last on the command hne does not ovemde the other). 

Selt'cte the visible process for display. If yon do not specify /VISIBLE, it is 
assumed by default. 


Description 


The SHOW PROCESS command displays information about specified processes 
and any images running in those processes. 

When used with the /FULL qualifier, the SHOW PROCESS command also^ 

displays information about the availability and use ggg^tor 

information that is useful if you are debugging a program that uses vect 

instructions. 

^ in a ^HOW PROCESS display as soon as it comes 

A process can first appear in a oxiu • cprnw PROCESS 

under debugger control. A process can no longer appear in a SH 
display if it is terminated through an EXIT or QUIT comman . 

By default (/BRIEF), one line of information is displayed for each process, 
including the following: 

. The process number assigned by the debugger. A 

• The VMS process name. 
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SHOW PROCESS 




Whether the process has been put on hold with 
command. 


a SET PROCESS/HOLD 






The current debugging state for that process (see Table CD-I). 

The location (symbolized, if possible) at which execution of the 
suspended in that process. 


image is 


Table CD-I 
State 


Debuggin g States 

Description 


Activated 


Break 

Break on branch 
Break on call 
Break on instruction 
Break on lines 
Break on modify of 
Break on return 
Exception break 
Excep. break preceding 
Interrupted 


Step 

Step on return 
Terminated 


Trace 

Trace on branch 
Trace on call 
Trace on instruction 
Trace on lines 
Trace on modify of 
Trace on return 
Exception trace 
Excep. trace preceding 
Unhandled exception 
Watch of 


The image and its process have just been brought 

under debugger control, either through a RUN 
/DEBUG command at DCL level, a debugger 
CONNECT command, a Ctrl/Y—DEBUG sequence, or 
by the program signaling SS$_DEBUG while it was 
not under debugger control. 

A breakpoint was triggered. 


Execution was interrupted in that process, either 
because execution was suspended in another process, 
or because the user interrupted program execution 
with the abort-key sequence (Ctrl/C by default). 

A STEP command has completed. 

The image indicated has terminated execution but 
the process is still under debugger control. Therefore, 
you can obtain information about the image and its 
process. You can use the EXIT or QUIT command to 
terminate the process. 

A tracepoint was triggered. 


An unhandled exception was encountered. 
A watchpoint was triggered. 
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SHOW PROCESS 


Examples 


The SHOW PROCESS/FULL gives additional information about processes (see 

the examples). 

Related commands: 

CONNECT 

Ctrl/C 

DEFINE/PROCESS_GROUP 

EXIT 

QUIT 

SET PROCESS 


1 DBG 2> SHOW PROCESS 

Number Name Hold State SCREENULINE 47 

* 2 WTA3: HOLD break SCREENNoLiNb 4/ 

DBG_2> “ 

The SHOW PROCESS command, by default, displays one line of information 

about the visible process (which is identified with an aster1 ®^ . th 
leftmost column. The process has the VMS process name _WTA 3 .. It is the 
second process brought under debugger control (process number 2UU n 
hold, and the image’s execution is suspended at a breakpoint at line 

module SCREEN. 

2. DBG_2> SHOW PROCESS/FULL %PREVIOUS_PROCESS name; J0NES _1: 

s: s No nu er ‘ visibie p r ° cess: no 

Current PC: TEST_VALVES\%LINE 153 

SriowSsS” pt5d ( 

Current/Base priority: 5/4 Termina . 


Image name: USERS:(JONES.PR0G11TEST_VALVES.EXE;31 


Elapsed CPU time: 0 00:03:17.17 
Buffered I/O Count: 14894 
Direct I/O Count: 695 ° 
Open file count: 1 
Enqueue count: ^ uu 
Vector capable: Yes 
Vector consumer: Yes 
Fast Vector context switches: 0 
Current working set size: 1102 
Current working set extent: 12288 
Peak working set size: 4955 
Current virtual size: 255 
Page faults: 4135s 


CPU Limit: Infinite 

Remaining buffered I/O quota: 
Remaining direct I/O quota: 
Remaining open file quota: 
Remaining enqueue quota: 


80 

40 

43 

198 


Vector CPU time: 00:00:00.00 
Slow Vector context switches: 0 
Working set size quota: 1304 
Maximum working set extent: 

Maximum authorized working set: 1304 
Peak virtual size: 


Active ASTs: 
Event flags: 
DBG 2> 


FF800000 60000003 


Remaining AST Quota: 
Event flag wait mask: 


27 

7FFFFFFF 


The SHOW PROCESS/FULL %PREVIOUS_PROCESS commend displays the 
rimum level of information about the previoue process m the circular list 
of processes (process number 1, in this case). 


CD-232 






Debugger Command Dictionary 
SHOW PROCESS 


DBG_2> SHOW PROCESS IPROCESS NAME TEST 3 
Number Name Hold State "Current PC 

' wa tch of TEST_3\ROUT4\COUNT 

DBG 2> TEST_3\%LINE 54 

processTOST > 3°Th^ “ mmand °ne Une of information about 

process lEbT_3. The image is suspended at a watchpoint of variable COUNT. 

DBG_2> SHOW PROCESS/DYNAMIC 
Dynamic process setting is enabled 
DBG_2> 

™ing"°LX CESS/DYNAMIC COmmand indicates that dynamic P^ aa 
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SHOW RADIX 


Format 


Identifies the current radix for the entry and display of integer data or, if the 
/OVERRIDE qualifier is specified, the current override ra x. 


SHOW RADIX 


Qualifiers 

/OVERRIDE 

Identifies the current override radix. 


Description 


Examples 


The debugger can interpret and cheplay tag-** * 

binary, decimal, hexadecimal, and oct . RADIX 

display of radix for both entry and 

S^Pu”raS T ^u“dht 

except BLISS and MACRO. It is hexadecimal for BLISS and MACKU. 

The current override radix tor the display of all data is the.ovemde radbcUst 
With the SET RADIX/OVERRIDE command. If no SET RADIX 
/OVERRIDE command was entered, the override radix is none 

Related commands: 

DEPOSIT 

EVALUATE 

EXAMINE 

(SET,CANCEL) RADIX 


1. DBG> SHOW RADIX 
input radix: decimal 
output radix: decimal 
DBG> 

This command identifies the input radix and output radix as decimal. 

2. DBG> SET RADIX/OVERRIDE HEX 
DBG> SHOW RADIX/OVERRIDE 

output override radix: hexadecimal 

DBG> 

_ qft TCADIX/OVERRIDE command sets the override 

ractatohSedmal and the SHOW RADIX/OVERRIDE command mficatee 

the override radix. This means that all data is displayed as hexadeci 
integer data in commands such as EXAMINE and so on. 
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SHOW SCOPE 


Format 


Identifies the current scope search list for symbol lookup. 


SHOW SCOPE 


Description 


he current scope search list designates one or more program locations (specified 
by pathnames or other special characters) to be used in the interpretation of 
symbols that are specified without pathname prefixes in debugger commands. 

Jp® C ™^ Scope sea rch list is the scope search list last established with the 
SET SCOPE command. If no SET SCOPE command was entered, the current 
scope search list is 0,1,2, . . . ,n by default. 

The default scope search list specifies that, for a symbol without a pathname 
prefix, a symbol lookup such as "EXAMINE X" first looks for X in the routine 
that !s currently executing (scope 0); if no X is visible there, the debugger looks 
m the caller of that routine (scope 1), and so on down the call stack; if X is not 
in scope n , the debugger searches the rest of the run-time symbol table 
(Kb L)— that is, all set modules and the global symbol table (GST), if necessary. 

If you have used a decimal integer in the SET SCOPE command to represent a 
routine m the call stack, the SHOW SCOPE command displays the name of the 
routine represented by the integer, if possible. 

Related commands: (SET,CANCEL) SCOPE. 


Examples 


1. DBG> CANCEL SCOPE 
DBG> SHOW SCOPE 
scope: 

* 0 [ = EIGHTQUEENS\TRYCOL\REMOVEQUEEN ] 

1 [ = EIGHTQUEENS\TRYCOL ], 

2 [ = EIGHTQUEENS\TRYCOL 1 ], 

3 [ = EIGHTQUEENS\TRYCOL 2 ], 

4 [ = EIGHTQUEENS\TRYCOL 3 ], 

5 [ = EIGHTQUEENS\TRYCOL 4 ], 

6 t = EIGHTQUEENS ] 

DBG> SET SCOPE/CURRENT 2 
DBG> SHOW SCOPE 

scope: 

0 [ = EIGHTQUEENS\TRYCOL\REMOVEQUEEN 1 
1 [ = EIGHTQUEENS\TRYCOL ], 

* 2 [ = EIGHTQUEENS\TRYCOL 1 ], 

3 [ = EIGHTQUEENS\TRYCOL 2 ], 

4 [ = EIGHTQUEENS\TRYCOL 3 ], 

5 [ = EIGHTQUEENS\TRYCOL 4 ], 

6 [ = EIGHTQUEENS ] 
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2 . 


The CANCEL SCOPE command restores the default scope search list ’ 
which is displayed by the (first) SHOW SCOPE command. In this example, 
Mention is suspended at routine REMOVEQUEEN, after several recursive 
calls to routine TRYCOL. The asterisk (*) indicates that the scope search 
s^rts ^cope 0, the scope of the routine in which execution is suspended. 

The command SET SCOPE/CURRENT resets the start of the scope search 
hst toT c re 2. Scope 2 is the scope of the caller of the caller of the routine 
in which execution is suspended. The asterisk in the output of the (s ^° } 

SHOW SCOPE command indicates that the scope search hst now starts with 

scope 2. 

DBG> SET SCOPE 0,STACKS\R2,SCREEN_I0, \ 

DBG> SHOW SCOPE 
scope: 

0, [= TEST ], 

STACKS\R2, 

SCREEN_IO, 

\ 

DBG> 

In this example, the SET SCOPE command directs the debugger to look for 
symbols without pathname prefixes according to the following SC0 P. e 
list. First the debugger looks in the PC scope (denoted by " ^ c ^ 

module TEST). If the debugger cannot find a specified symbol in the P , 

it then looks in routine R2 of module STACKS; if necessary, it then looks m 
module SCREEN_IO, and then finally in the global symbol table (denote 
by the global scope, \). The SHOW SCOPE command identifies thecurrent 
scope search list for symbol lookup. No asterisk is shown in the SHOW 
SCOPE display unless the default scope search list is in effect or you have 
previously entered a SET SCOPE/CURRENT command. 
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SHOW SEARCH 


Identifies the default qualifiers (/ALL or /NEXT, /IDENTIFIER or /STRING) 
currently in effect for the SEARCH command. 


Format 


SHOW SEARCH 


Description 


Example 


T1 f“ qualifiers for the SEARCH command are the default qualifiers last 
established with the SET SEARCH command. If no SET SEARCH command was 
entered, the default qualifiers are /NEXT and /STRING. 

Related commands: 

SEARCH 

(SET,SHOW) LANGUAGE 
SET SEARCH 


DBG> SHOW SEARCH 

search settings: search for next occurrence, as a strina 
DBG> SET SEARCH IDENT y 

DBG> SHOW SEARCH 

search settings: search for next occurrence, as an identifier 
DBG> SET SEARCH ALL 
DBG> SHOW SEARCH 

search settings: search for all occurrences, as an identifier 
DBG> 

J n “ s " rst SH0W SEARCH command displays the default settings 

for the SET SEARCH command. By default, the debugger searches for and 
displays the next occurrence of the string. 

The second SHOW SEARCH command indicates that the debugger searches for 
the next occurrence of the string, but displays the string only if it is not bounded 

on either side by a character that can be part of an identifier in the current 
language. 

The third SHOW SEARCH command indicates that the debugger searches for all 
occurrences of the string, but displays the strings only if they are not bounded 

language ^ 3 Character that can be part of an identifier in the current 
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SHOW SELECT 


Identifies the displays currently selected for each of the display attributes: error, 
input, instruction, output, program, prompt, scroll, and source. 


Format 


SHOW SELECT 


Description 


The display attributes have the following properties: 

. A display that has the error attribute displays debugger diagnostic 
messages. 

• A display that has the input attribute echoes your debugger input. 

. A display that has the instruction attribute displays the decoded assembly 
language instruction stream of the routine being debugged. The display 
updated when you enter an EXAMINE/INSTRUCTION command. 

. A display that has the output attribute displays any debugger output that 
is not directed to another display. 

. A display that has the program attribute displays program input and 

output. Currently only the PROMPT display can have the program attribute. 

. A display that has the prompt attribute is where the c 

input. Currently, only the PROMPT display can have the PROMPT attribute. 

. A display that has the scroll attribute is the default display for the 
SCROLL, MOVE, and EXPAND commands. 

. A display that has the source attribute displays the source code of the 
module being debugged, if available. The display is updated when you enter 
a TYPE or EXAMINE/SOURCE command. 


Related commands: 

SELECT 
SHOW DISPLAY 


Example 


DBG> SHOW SELECT 
display selections: 
scroll = SRC 


input = none 
output = OUT 
error = PROMPT 
source = SRC 
instruction = none 
program = PROMPT 
prompt = PROMPT 


this example, the SHOW SELECT command identifies the displays currently 
Xd for each of the display attributes. The display selections shown are the 

fault selections for all languages. 
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SHOW SOURCE 


Identifies the source directory search lists currently in effect. 

Format 

SHOW SOURCE 

Qualifiers 

/EDIT 

Applies mainly to Ada programs. 

Identifies the search list for source files to be edited when you use the EDIT 
command. 


Description 


(h ! ectory search list has not been established by means of the SET 
° r SET SOURCE/MODULE=moo? n^-nawe commands, the SHOW 
bOURCE command indicates that no directory search list is currently in effect 
in this case, the debugger expects each source file to be in the same directory ' 
that it was mat compile time (the debugger also checks that the version number 
and the creation date and time of a source file match the information in the 
debugger s symbol table). 

The SET SOURCE/MODULE=moc/u/e-7iame command establishes a source 
directory search list for a particular module. The SET SOURCE command 
establishes a source directory search list for all modules not explicitly mentioned 
m a SET SOURCE/MODULE=mo<i«/e-name command. When those commands 
have been used, the SHOW SOURCE command identifies the source directory 
search list associated with each search categories. 

The iS? IT q “ alifier is needed when th e hies used for the display of source code 
are different from the files to be edited by means of the EDIT command. This is 
the case with Ada programs. For Ada programs, the SHOW SOURCE command 
i entities the search list of tiles used for source display (the "copied" source files 

m Ada P™f a “ hbrarie s); the SHOW SOURCE/EDIT command identifies the 
search list for the source files you edit when using the EDIT command. 

See Section E.1.5 and Section E.1.6 for information specific to Ada programs. 
Related commands: 


(SET,SHOW) MAX_SOURCE_FILES 
(SET,CANCEL) SOURCE 
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SHOW SOURCE 


Examples 


DBG> SHOW SOURCE 

no directory se&rch list in effect 

DBG> SET SOURCE [PROJA],[PROJB],DISK:[PETER.PROJC] 

DBG> SHOW SOURCE 

source directory search list for all modules. 

[PROJA] 

[PROJB] 

DISK:[PETER.PROJC] 

DBG> 

In this example, the SET SOURCE command directs the debugger to search 
IS [PROJAUPKOJB], and DISMPETER.PROJC). 

DBG> SET SOURCE/MODULE=COBOLTEST [], DISK$2:[PROJD] 

DBG> SHOW SOURCE 

source directory search list for COBOLTEST: 

[] 

DISKS2:[PROJD] 

source directory search list for all other modules: 

[PROJA] 

[PROJB] 

DISK:[PETER.PROJC] 

DBG> 

In this example, the SET SOURCE command directs the debugger to search 
the mr«n7defanlt directory (U> and directory DISK$2:[PROJD] for soum, 
files to use with the module COBOLTEST. 
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SHOW STACK 


Displays information from the current call stack. 

Format 

SHOW STACK [integer] 

Parameters 

integer 

Specifies the number of frames to display. If you omit the parameter, the 
debugger displays information about all call stack frames. 

Description 

For each call frame, the SHOW STACK command displays information such 
as the condition handler, saved register values, and the argument list, if any. 

he latter is the list of arguments passed to the subroutine with that call. In 
some cases the argument list can contain the addresses of actual arguments. In 

such cases, use the EXAMINE address command to display the values of these 
arguments. 

Related command: SHOW CALLS. 


Example 


DBG> SHOW STACK 

stack frame 0 (2146814812) 


condition handler: 0 


SPA: 

0 

S: 

0 

mask: 

A M<R2> 

PSW: 

0000 (hexadecimal) 

saved AP: 

7 

saved FP: 

2146814852 

saved PC: 

EIGHTQUEENSULINE 

saved R2: 

0 


argument list: (1) EIGHTQUEENSULINE 


(2146814852) 

handler: SHARE$PASRTL+888 
0 
0 

none saved 

0000 (hexadecimal) 

2146814924 

2146814904 

SHARE$DEBUG+667 


stack frame 1 
condition 
SPA: 

S: 

mask: 

PSW: 

saved AP: 
saved FP: 
saved PC: 

DBG> 


69 

68+2 


In this example, the SHOW STACK command displays information about 
stack frames at the current PC location. 


all call 
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SHOW STEP 

Identifies the default qualifiers (/INTO, /INSTRUCTION, /NOS1LENT and so on) 
currently in effect for the STEP command. 


Format 

SHOW STEP 


Description 


The default qualifiers for the STEP command are the default qualifiers last 
established by the SET STEP command. If n<.SET'STEP—d'.as entered, 
the default qualifiers are /LINE, /OVER, /NOSILENT, and /SOURCE. 

If you invoke screen mode with the keypad-key sequence PF1-P F3 ’SET 
STEP NOSOURCE command is issued in addition to the SET MODE SCRE 
command (to eliminate redundant source display in output and /OVTER 

In that case, the default qualifiers for the STEP command are /LINE, /OVER, 
/NOSILENT, and /NOSOURCE. 

Related commands: 


STEP 
SET STEP 


Example 

DBG> SET STEP INTO,NOSYSTEM,NOSHARE,INSTRUCTION,NOSOURCE 

step type: nosystem, noshare, nosource, nosilent, into routine calls, 
by instruction 

DBG> 

In this example, the SHOW STEP command indicates that the debugger take the 
following action: 

• Steps into called routines, but not those in system space or in shareable 
images 

• Steps by instruction 

• Does not display lines of source code while stepping 
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SHOW SYMBOL 


Format 


Displays information about the symbols in the debugger’s run-time 
(RST) for the current image. 


symbol table 


SHOW SYMBOL symbol-name[, ... ] [IN scope[, ... ]] 

Parameters 


symbol-name 

Specifies a symbol to be identified. A valid symbol name is a single identifier or a 

ab pLn a ^ e r?t t T^ e T S™ %LABEL n > where n is an integer. Compound names such 
as RECORD.FffiLD or ARRAY[1,2] are not valid. If you specify the asterisk (*) 

wildcard character by itself, all symbols are listed. You can use * within a symbol 
name. J 


scope 

Specifies the name of a module, routine, or lexical block, or a numeric scope. It 
has the same syntax as the scope specification in a SET SCOPE command and 
can include pathname qualification. All specified scopes must be in set modules 
in the current image. 

The SHOW SYMBOL command displays only those symbols in the RST for 
the current image that both match the specified name and are declared within 
the lexical entity specified by the scope parameter. If the scope parameter is 
omitted, all set modules and the global symbol table (GST) for the current image 
are searched for symbols that match the name specified by the symbol-name 
parameter. 


Qualifiers 

/ADDRESS 

Displays the address specification for each selected symbol. The address 
specification is the method of computing the symbol’s address. It can merely 
e the symbols memory address, but it can also involve indirection or an offset 
from a register value. Some symbols have address specifications too complicated 
to present in any understandable way. These address specifications are labeled 
"complex address specifications." 

/DEFINED 

Displays symbols you have defined with the DEFINE command (symbol 
definitions that are in the DEFINE symbol table). 

/DIRECT 

Displays only those symbols that are declared directly in the scope parameter 
bymbols declared in lexical entities nested within the scope specified by the scope 
parameters are not shown. 


/LOCAL 

Displays symbols that are defined with the DEFINE/LOCAL command (symbol 
definitions that are in the DEFINE symbol table). 

/TYPE 

Displays data type information for each selected symbol. 
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/USE_CLAUSE 

Applies to Ada programs. 

Identifies any Ada package that a specified block, subprogram, or package names 
fa “eTuse If the symbol specified is a package, also idenbfies any block, 
subprogram, package, and so on that names the specified symbol m a use clause. 


Description 


Note 


The current image is either the main image (by default) or the image 
estabhshed as the current image by a previous SET IMAGE command. 


The SHOW SYMBOL command displays information that the debugger has about 
I jvtnZbol in the current image. This information might not be the same as 
what the compiler had or even what you see in your source code. Nonethe ^ ss ’ * 
is useful for understanding why the debugger might act as it does when handling 

symbols. 

If you do not specify a qualifier, the SHOW SYMBOL command lists all of the 
possible declarations or definitions of a specified symbol that east. m ^RST 

for the current image-that is, in all set modules and in the GST for that image. 
Symbols are displayed with their pathnames. A pathname identifies the search 
scope (module, nested routines, blocks, and so on) that the debugger mus o ow 
to reach a particular declaration of a symbol. When specifying symbolic^address 
expressions in debugger commands, you need to use pathnames only 1 y 
is defined multiple times and the debugger cannot resolve the ambiguity. 

The /DEFINED and /LOCAL qualifiers display information about symbols 
defined with the DEFINE command (not the symbols that are derived fromyour 
program). The other qualifiers display information about symbols defined wit 


your program. 

See Section E.1.12 and Section E.1.13 for information specific to Ada programs. 


Related commands: 

DEFINE 

DELETE 

SET MODE [NO]LINE 
SET MODE [NOjSYMBOLIC 
SHOW DEFINE 
SYMBOLIZE 


Examples 

1. DBG> show SYMBOL I 
data FORARRAY\I 
DBG> 

This command shows that symbol I is defined in module FORARRAY and is a 
variable (data) rather than a routine. 
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DBG> SHOW SYMBOL/ADDRESS INTARRAY1 
data F0RARRAYUNTARRAY1 

descriptor address: 0009DE8B 

DBG> 

This command shows that symbol INTARRAY1 is defined in module 
FORARRAY and has a memory address of 0009DE8B. 

DBG> SHOW SYMBOL *PL* 

This command lists all the symbols whose names contain the string "PL". 

DBG> SHOW SYMBOL/TYPE COLOR 
data SCALARS\MAIN\COLOR 

enumeration type (primary, 3 elements), size: 4 bytes 

This command shows that the variable COLOR is an enumeration type. 

DBG> SHOW SYMBOL/TYPE/ADDRESS * 

This command displays all information about all symbols. 

DBG> SHOW SYMBOL * IN M0D3\C0UNTER 
routine M0D3\C0UNTER 
data MOD3\COUNTER\X 
data MOD3\COUNTER\Y 

DBG> 

This command lists all the symbols that are defined in the scope denoted bv 
the pathname MOD3\ COUNTER. 

DBG> DEFINE/COMMAND SB=SET BREAK 
DBG> SHOW SYMBOL/DEFINED SB 
defined SB 

bound to: SET BREAK 
was defined /command 

DBG> 

In this example, the DEFINE/COMMAND command defines SB as a symbol 
for the command SET BREAK. The SHOW SYMBOL/DEFINED command 
displays that definition. 
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SHOW TASK 

Displays information about the tasks of a tasking program (also called a 
multithread program). 


Format 

SHOW TASK [task-spec[, . . . ]] 


Parameters 


task-spec . 

Specifies a task value. Use any of the following forms: 

• A task (thread) name as declared in the program, or a language expression 
that yields a task value. You can use a pathname. 

. A task ID (for example, %TASK 2), as indicated in a SHOW TASK display. 




One of the following task built-in symbols: 

%ACTIVE_TASK The task that runs when a GO, STEP, CALL, or 

EXIT command executes. 


%CALLER_TASK (Applies only to Ada programs.) When an accept 

statement executes, the task that called the entry 
associated with the accept statement. 

%NEXT TASK The task after the visible task in the debugger s 

task list. The ordering of tasks is arbitrary but 
consistent within a single run of a program. 


%PREVIOUS_TASK The task previous to the visible task in the 

debugger’s task list. 

%VISIBLE_TASK The task whose call stack and register set are the 

current context for looking up symbols, register 
values, routine calls, breakpoints, and so on. 


Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. 
For details on how to specify tasks with particular qualifiers, see the qualifier 
descriptions. If you do not specify a task or a task selection qualifier (/AL , 
/[NO]HOLD, /PRIORITY, /STATE), the visible task is selected for display. 


Qualifiers 

Selects all existing tasks for display—namely, tasks that have been created and 
(in the case of Ada tasks) whose master has not yet terminated. 

See the description section for the effect of the current event facility. Do not 
specify a task with /ALL. 

Does a SHOW CALLS command for each task selected for display. This identifies 
the currently active routine calls (the call stack) for a task. 

Displays additional information for each task selected for display. The /FULL 
qualifier provides additional information if used either by itself or with the 
/CALLS or /STATISTICS qualifier. 
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Description 


/HOLD 

/NOHOLD 

Selects either tasks that are on hold, or tasks that are not on hold for display. 

If you do not specify a task, /HOLD selects all tasks that are on hold. If you 
specify a task list, /HOLD selects the tasks in the task list that are on hold. 

If you do not specify a task, /NOHOLD selects all tasks that are not on hold. If 
you^specify a task list, /NOHOLD selects the tasks in the task list that are not on 

See the description section for the effect of the current event facility. 

/PRIORITY=(n[, ... ]) 

If you do not specify a task, selects all tasks having any of the specified priorities 
n where „ is a decimal integer from 0 to 15. If you specify a task list, selects the’ 
tasks m the task list that have any of the priorities specified. 

See the Description section for the effect of the current event facility. 

/STATE=(state[, ... ]) 

If you do not specify a task, selects all tasks that are in any of the specified 
states—RUNNING, READY, SUSPENDED, or TERMINATED. If you specify a 
ask list, selects the tasks in the task list that are in any of the states specified. 

See the description section for the effect of the current event facility. 

/STATISTICS 

Displays task statistics for the entire tasking system. This information enables 
you to measure the performance of your tasking program. The larger the number 
of total schedulings (also known as context switches), the more tasking overhead 
thesis. When you specify /STATISTICS, the only other permissible qualifier is 

/TIME_SLICE 

TASKmiirp 6 STn? time ' SliC f V * lue ’ in seconds > as specified by a previous SET 
TASK/TIME_SLICE command. If no SET TASK/TIME_SLICE command was 

previously entered, displays the time-slice value, if any, that was specified in the 
program. 

U no time-slice value was previously established, the value is 0.0—that is time 
slicing is disabled. 

Do not specify another qualifier when you specify /TIME_SLICE. 


A task can first appear in a SHOW TASK display as soon as it is created. A task 
can no longer appear in a SHOW TASK display if it is terminated or (in the case 

taw™ taskl J n i pr ? gram) lf lts master is terminated. By default, the SHOW 
1ASK command displays one line of information for each task selected. 

Related commands: 

DEPOSIT/TASK 

EXAMINE/TASK 

(SET,SHOW) EVENT_FACILITY 

SET TASK 
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Examples 

1 . DBG> SHOW EVENT_FACILITY 
event facility is ADA 


DBG> SHOW TASK/ALL 

task id pri hold state substate task ob]ect 

* %TASK 1 7 RUN 122624 

ITASK 2 7 HOLD SUSP Accept h40HECK°IN 

%TAS K 3 6 READY Entry call H 4 .CHECK_IN 

DBG> 

In this example, the SHOW EVENT_FACILITY command identifies ADA as 
the current event facility. The SHOW TASK/ALL command provides basic 
information about all the tasks that were created through Ada services an 
currentiy exist. One line is devoted to each task. The active task is marked 
with an asterisk (*). In this example, it is also the active task (the task th 

is in the RUN state). 

2 DBG> SHOW TASK IACTIVE TASK,ITASK 3,MONITOR 

This command selects the active task. %TASK 3, and task MONITOR for 
display. 

3. DBG> SHOW TASK/PRI0RITY=6 

This command selects all tasks with priority 6 for display. 

4. DBG> SHOW TASK/STATE=(RUN,SUSP) 

This command selects all tasks that are either running or suspended for 
display. 

5 . DBG> SHOW TASK/STATE=SUSP/NOHOLD 

This command selects all tasks that are both suspended and not on hold for 
display 

6 . DBG> SHOW TASK/STATE=(RUN,SUSP)/PRI0=7 %VISIBLE_TASK,%TASK 3 

This command selects for display those tasks among the visible task and 
%TASK 3 that are in either the RUNNING or SUSPENDED STATE an ave 

priority 7. 
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SHOW TERMINAL 


fo™at fi outp h ut CUrrent terminaI SCreen hdght (pag6) and Width b6ing USed t0 


Format 

SHOW TERMINAL 


Description 


e T in o a i™ en height and width are the height and width last 
ablished by the SET TERMINAL command. If no SET TERMINAL command 

’ the , current height and width are, by default, the height and 

SHOV^TERMTNA^ ^ driver > as dis P la y ed by the DCL command 

SHOW TERMINAL (usually 24 lines and 80 columns, respectively, for VT-series 


Related commands: 

SET TERMINAL 
SHOW DISPLAY 
SHOW WINDOW 

Example 

DBG> SHOW TERMINAL 
terminal width: 80 
page: 24 

DBG> 


This command displays the current terminal 
80 columns and 24 lines, respectively. 


screen width and height (page) 


as 
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SHOW TRACE 

Displays information about tracepoints. 

Format 


Qualifiers 


Description 


SHOW TRACE 


/PREDEFINED 

Displays information about predefined tracepoin s. 

/USER 

Displays information about user defined tracepoints. 

The SHOW TRACE command displays information about n tr ® ce PO“ lts 
currently set, including any options such as WHEN or DO clauses, /AF 

counts, and so on. 

Rv default SHOW TRACE displays information about both user defined and 
predefined’tracepoints (if any). This is equivalent to entenng the comman 
SHOW TRACE/USER/PREDEFINED. User defined tracepoints are set with the 
SET TRACE command. Predefined tracepoints are set automatically when you 
f„™ke the dtor, and they depend on the type of program you are debugging. 
See Chapter 10 for information about predefined tracepoints that are associa e 
with multiprocess programs. 

Tf vou established a tracepoint using the /AFTER:n qualifier with the SET TRACE 
command the SHOW TRACE command displays the current vahie of the decimal 
integer n that is, the originally specified integer value minus one for each time 
the tracepoint location was reached. (The debugger decrements n each time 
Z tracepoint location is reached until the value of » is zero, at which time the 
debugger takes trace action.) 


Examples 


Related commands: (SET,CANCEL) TRACE. 


DBG> SHOW TRACE 

tracepoint at routine CALC\MULT 

tracepoint^" calls: ^ ^ ^ CAL LG CALLS 

DBG> 

The SHOW TRACE command identifies all tracepoints that are currently set. 
This example indicates user defined tracepoints that are triggered whenever 
SX“?eaches routine MULT in module CALC or one of the instructions 
RET, RSB, BSBB, JSB, BSBW, CALLG, or CALLS. 
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DBG_2> SHOW TRACE/PREDEFINED 

predefined tracepoint on program activation 

DO (SET DISP/DYN/REM/SIZE:64/PROC SRC_/SUF=PROCESS NU AT HI SOURCE 
(EXAM/SOURCE .%SOURCE_SCOPE\$PC); 

SET DISP/DYN/REM/SIZE:64/PROC INST_/SUF=PROCESS NU AT HI INST 
(EXAM/INSTRUCTION .0\%PC)) ~ 

predefined tracepoint on program termination 
DBG 2> 

This command identifies the predefined tracepoints that are currently set. 

hv h - a “ ple Sh °7 S the predefined tracepoints that are set automatically 
Dy tfte debugger for a multiprocess program (when DBG$PROCESS has 
, e Va Ue MULTIPROCESS). The tracepoint on program activation triggers 
whenever a new process comes under debugger control. The DO clause 
creates a process-specific source display named SRC_« and a process-specific 

istw' 011 /'? 3 ! named INST -" when ever a process activation tracepoint 
s triggered. The tracepoint on program termination triggers whenever a 
process does an image exit. 
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SHOW TYPE 


Identifies the current type for program locations 
generated type or, if the /OVERRIDE qualifier is 
type. 


that do not have a compiler- 
specified, the current override 


Format 

SHOW TYPE 

Qualifiers 

/OVERRIDE 

Identifies the current override type. 


Description 


The current type for program locations that donot have a 

type is the type last established by the SET TYPE command. If no SET TYPE 
command was entered, the type for those locations is longword integer. 

The current override type for all program locations is the ovenidetype 
last established by the SET TYPE/OVERRIDE command. If no SET TYPE 
/OVERRIDE command was entered, the override type is "none". 


Related commands: 

CANCEL TYPE/OVERRIDE 

DEPOSIT 

EXAMINE 

(SET,SHOW,CANCEL) MODE 
(SET,SHOW,CANCEL) RADIX 
SET TYPE 


Examples 


1. 


DBG> SET TYPE QUADWORD 
DBG> SHOW TYPE 
type: quadword integer 
DBG> 


fis command sets the type for locations that do not have a compiler 
nerated type to quadword. The SHOW TYPE command displays the 
irrent defeat type for those locations as quadword integer. This means that 
ie debugger interprets and displays entities at those locations as quadwor 
tegers unless you specify otherwise (for example with a type qualifier on the 
FAMINE command). 


2 . 


DBG> SHOW TYPE/OVERRIDE 
type/override: none 
DBG> 


This command indicates that no override type has been defined. 
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SHOW VECTOR MODE 

Identifies the current vector mode (synchronized or nonsynchronized). 
Applies to vectorized programs. 


Format 


Description 


SHOW VECTOR MODE 


The current vector mode is the mode established with the SET VECTOR MODE 

command If no SET VECTOR_MODE command was entered, the vector mode is 
by default, nonsynchronized. 

Related commands: 


SET VECTOR.MODE [NOJSYNCHRONIZED 
SYNCHRONIZE VECTOR_MODE 

Example 


DBG> SHOW VECTOR_MODE 

Vector mode is nonsynchronized 

DBG> SET VECTOR_MODE SYNCHRONIZED 

DBG> SHOW VECT0R_M0DE 

Vector mode is synchronized 

DBG> 

SHOW VECTOR_MODE command indicates the effect of the SET VECTOR 
MODE command. “ 
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SHOW WATCH 

Displays information about watchpoints. 


Format 


Example 


SHOW WATCH 


Description 


The SHOW WATCH command displays information about watchpoints that are 
currently set, including any options such as WHEN or DO clauses, /AFTER 
counts, and so on. 

If you established a watchpoint using the /AFTER:n qualifier with the SET 
WATCH command, the SHOW WATCH command displays the current value of 
the decimal integer n, that is, the originally specified integer value minus one for 
each time the watchpoint location was reached. (The debugger decrements n 
time the watchpoint location is reached until the value of n is zero, at which tim 
the debugger takes watch action.) 

Related commands: (SET,CANCEL) WATCH. 


dbg> show watch 

watchpoint of MAIN\X 
watchpoint of SUB2\TABLE+20 
DBG> 

This command displays two watchpoints, one at the variable X (defined in module 
MAIN), and the other at the location SUB2\TABLE+20 (20 bytes beyond t e 
address denoted by the address expression TABLE). 
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SHOW WINDOW 


Identifies the name and screen position of predefined and user-defined 
screen-mode windows. 


Format 


SHOW WINDOW [window-name[, ... ]] 

Parameters 


Qualifiers 


windowname 

Specifies the name of a screen window definition. If you do not specify a name, or 
if you specify the asterisk (*) wildcard character by itself, all window definitions 
are listed. You can use * within a window name. Do not specify a window 
definition name with /ALL. 


/ALL 

Lists all window definitions. Do not specify a window definition name with /ALL. 

Description 


Related commands: 

(SET,SHOW,CANCEL) DISPLAY 
(SET,SHOW) TERMINAL 
(SET,CANCEL) WINDOW 
SHOW SELECT 


Example 


DBG> SHOW WINDOW LH*,RH* 
window LH1 at (1,11,1,40) 
window LH12 at (1,23,1,40) 
window LH2 at (13,11,1,40) 
window RH1 at (1,11,42,39) 
window RH12 at (1,23,42,39) 
window RH2 at (13,11,42,39) 

DBG> 

This command displays the name and screen position of all screen window 
definitions whose names starts with LH or RH. 


CD-255 










Debugger Command Dictionary 
SPAWN 



SPAWN 


Creates a subprocess, enabling you 
terminating a debugging session or 


to execute DCL commands without 
losing your debugging context. 


Format 

SPAWN [DCL-command] 


Parameters 


Specifies a DCL command. If you specify a DCL command, the command 
executed in a subprocess. Control is returned to the debugging session when the 
DCL command terminates. 

If you do not specify a DCL command, a subprocess is created and y 01 J can then 
enter DCL commands. Either logging out of the spawned process or-attaching; to 
the parent process (with the DCL command ATTACH) enables you to continu 
your debugging session. 

If the DCL command contains a semicolon, you must enclose the command in 
quotation marks (»). Otherwise the semicolon is interpreted as a debugger 
command separator. To include a quotation mark inside the string, enter two 
consecutive quotation marks ("")• 


Qualifiers 


Snecifiesanlnput DCL command file containing one or more DCL commands 
to be executed by the spawned subprocess. The default file type is .COM. If you 
specify a DCL command string with the SPAWN command and an input file with 
the /INPUT qualifier, the command string is processed before the in P u ^ e - 
processing of the input file is complete, the subprocess is terminated. Do not use 
the asterisk (*) wildcard character in the file specification. 

/OUTPUT-file-spec 

Writes the output from the SPAWN operation to the specified file. The default 
file type is .LOG. Do not use the asterisk (*) wildcard character in the file 

specification. 

/WAIT (default) 

Controls"whether the debugging session (the parent process) is sus P® n< * e< ? ^ le 
the subprocess is running. The /WAIT qualifier (default) suspends the debugging 
session until the subprocess is terminated. You cannot enter debugger comma 
nn t.il control returns to the parent process. 

The /NOWAIT qualifier executes the subprocess in parallel with the debugging 
session. You can enter debugger commands while the subprocess is ™nmng. 

If you use /NOWAIT, you should specify a DCL command with the SPAWN 
command; the DCL command is executed in the subprocess. A message indicates 
when the spawned subprocess completes. 
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Description 

The SPAWN command acts exactly like the DCL command SPAWN. You can edit 
hies, compile programs, read mail, and so on without ending your debugging 
session or losing your current debugging context. 

[ n DA a J T tion > y° u can s P awn a DCL command SPAWN. DCL processes the second 
oPAWN command, including any qualifier specified with that command. 

Related command: ATTACH. 

Examples 

1. DBG> SPAWN 
$ 

This command shows that the SPAWN command, with no parameter specified, 
creates a subprocess at DCL level. You can now enter DCL commands. Log 
out to return to the debugger prompt. 

2. DBG> SPAWN/NOWAIT/1NPUT=READ NOTES/OUTPUT=0428NOTES 
DBG> 

This command creates a subprocess that is executed in parallel with the 
debugging session. This subprocess executes the DCL command procedure 
READ_NOTES.COM. The output from the spawned operation is written to 
the file 0428NOTES.LOG. 


3. DBG> SPAWN/NOWAIT SPAWN/OUT=MYCOM.LOG @MYCOM 
DBG> 

This command creates a subprocess that is executed in parallel with the 
debugging session. This subprocess creates another subprocess to execute the 
DCL command procedure MYCOM.COM. The output from that operation is 
written to the file MYCOM.LOG. 
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STEP 


Executes the program up to the next line, instruction, or other specified location. 


Format 


STEP [integer] 


Parameters 


^decimal integer that specifies the number of step units (lines, instructions, and 
so on) to be executed. If you omit the parameter, the debugger executes one step 

unit. 


Qualifiers 


Executes the program to the next branch instruction. STEP/BRANCH has the 
same effect as SET BREAK/TEMPORARY/BRANCH,GO. 

Executes the program to the next call or RET instruction. STEP/CALL has the 
same effect as SET BREAK/TEMPORARY/CALL;GO. 

/EXCEPTION 

Executes the program to the next exception, if any. STEP/EXCEPTION has 
the same effect as SET BREAK/TEMPORARY/EXCEPTION ;GO. If no exception 
occurs, STEP/EXCEPTION has the same effect as GO. 

/INSTRUCTION[=(opcode[, ...])] 

If you do not specify an opcode, executes the prograni to the next mstrurtion. 
STEP/INSTRUCTION has the same effect as SET BREAK/TEMPORARY 
/INSTRUCTION;GO. 

If you specify one or more opcodes, executes the program to the next instruction 
whose opcode is specified in the list. STEP/INSTRUCTION ^opcodel .. . ]) 
has the same effect as SET BREAK/TEMPORARY/INSTRUCTION= 

{opcode [, ... ]);GO. 

If you specify a vector instruction, do not include an instruction qualifier (/U, /V, 
/M, /0, or /l) with the instruction mnemonic. 

Ifexecution is currently suspended at a routine call, STEP/INTO executes the 
program up to the beginning of that routine (steps into that r0 ^ tm ^ T Otherwise, 
STEP/INTO has the same effect as STEP without a qualifier. The /INTO quail er 
is the opposite of/OVER (the default behavior). 

The STEP/INTO behavior can be changed by also using the /[NO]JSB, 
/[NO]SHARE, and /[NO]SYSTEM qualifiers. 

/JSB 
/NO JSB 

Qualifies a previous SET STEP INTO command or a current STEP/INTO 
command. 
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It execution is currently suspended at a routine call and the routine is called 

has the same effect as STEP/OVER, 
erwise, SiEP/INTO/NOJSB has the same effect as STEP/INTO. 

STEMNTO/I^R /JSB hf 0 °"£S^ previous SET STEP NOJSB command, 
called by a JSB instrucf S & ^TO command to step into routines that are 
instruction B as wel1 as mto routines that are called by a CALL 

SB Q f^ 1S i th / default for a11 languages except DIBOL. The /NOJSB 
calledbvThe'CAW * ^ IB0L - DIB0L > application-declared routines are 
by tie JSB Ls^r ““ DIB ° L lib ^ called 

/LINE 

Executes the program to the next line of source code. However, the debugger 
skips over any source lines that do not result in executable code when compiled 

^EMR^^ySnHGO 11 ??’ ST f P/EI ^ E has the s ame effect as SET BREAK 
JiMt'URARY/LINEjGO. This is the default behavior for all languages. 

/OVER 

If execution is currently suspended at a routine call, STEP/OVER executes 

JoutiS^ m Th U e P /0 0 VER d ^ RET instruction ^eps over that 

routine). The /OVER qualifier is the default behavior and is the opposite of 

/RETURN 

Stmction^th^ir 6 m , W jV ch execution is currently suspended up to its RET 
calh^g routinef ThisP ht 6 P ° mt + JUSt prior to transferring control back to the 

SET BREAK/TE^^ ^ the Same effect as 

STEP/RETURN n executes the program up n levels of the call stack. 

/SHARE (default) 

/NOSHARE 

Command 3 SET STEP INT0 comma nd or a current STEP/INTO 

hf ^ SUSPend t at a ca “ 10 a shareable *“«• routine, STEP 

/NOSHAPF^fi, h he S J me effeCt aS STEP/ °VER. Otherwise, STEP/INTO 
/iNUbHARE has the same effect as STEP/INTO. 

Use STEP/INTO/SHARE to override a previous SET STEP 
STEP/INTO/SHARE enables a STEP/I^TO "d ”^re~ 4 

image routines, as well as into other kinds of routines. 

/SILENT 

/NOSILENT (default) 

Controls whether the -stepped to ... - message and the source line for the 
current location are displayed after the STEP has completed. The /NOSILENT 

that til* Sp6ClfieS that the messa £ e is displayed. The /SILENT qualifier specifies 

overtSes^SOTOCE ^ ’ ine "* ”°‘ displayeA The /SILENT 
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/SOURCE (default) 

displayed. The /SILENT qualifier overrides /SOURCE, bee also o 
[NOISOURCE. 

/SYSTEM (default) 

/NOSYSTEM qtfp TNTO command or a current 

/[NO]SYSTEM qualifies a previous SET bIRr 

STEP/INTO command. 

If execution is currently suspended at a call.« 

STEP/INTO/NOSYSTEM has the same effect as STEP/OVER. Othe 
/INTO/NOSYSTEM has the same effect as blEmiNiw. 

Use STEP/INTO/SYSTBM tooverride a predkm. SjWSTEP 

command STEP/INTO/SYSTEM enables a STEP/IN iU comma 
system routines, as well as into other kinds of routines. 

/VECTORJNSTRUCTION cjtfpa/TTTTOR 

Executes the program to the next j^eajotEMPORARY/VECTOR_ 

INSTRUCTION has the same effect as SET BRRAJVir- 

ttmstrT tction-.go. 


Description 


The STEP command is one of the four debugger commands that can be used to 
execute your program (the others are CALL, EXIT, and GO). 

The behavior of the STEP command depends on the following factors: 

• The default STEP mode previously established with a SET STEP command, if 
any 

• The qualifier specified with the STEP command, if any 

. The number of step units specified as parameter to the STEP command, if 

any 

Tf ™ qFT STEP command was previously entered, the debugger takes the 

you enter a STEP command without specrfymg a 

qualifier or parameter: 

1 Executes a line of source code (STEP/LINE is the default). 

2. Reports that execution has completed by issuing a "stepped to ... - message 
(STEP/NOSILENT is the default). 

3. Displays the line of source code at which execution is suspended (STEP 
/SOURCE is the default). 

4. Issues the prompt. 

The following STEP command qualifiers affect the location to which you step. 

/BRANCH 

/CALL 

/EXCEPTION 

/INSTRUCTION [=(opcode[, •••])] 

/LINE 
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/RETURN 

/vector_instruction 

The following qualifiers affect what output is seen upon completion of a step- 
/[NOJSILENT 
/[NOJSOURCE 

The following qualifiers affect what happens at a routine call: 

/INTO 

/[NOJJSB 

/OVER 

/[NOJSHARE 

/[NOJSYSTEM 

If you plan to enter several STEP commands with the same qualifiers vou 
can first use the SET STEP command to establish new default Qualifiers /for 

STEP comm^H S v M ' Then / ou do not have to those qualifiers with the 

of a LT STEP Can ?T emde ? e CUrrent dGfault ^ Ualifiers for duration 
™ g 7* ST ? P c ° mmand by s P ecif ymg other qualifiers. Use the SHOW STEP 
command to identify the current STEP defaults. 

InramS" bre t™j. nt ‘ S tnggcred (resulting from a SET BREAK 
S™ “ r a STEP/EXCEPTION command), execution is suspended 

exlrtio^h r o OTEP co ” d i‘ ion , h a'>' n “ * invoked. If you then resume 
™“ '’ n Wlth tl 'e STEP command, the debugger resignals the exception and the 
p gram executes to the beginning of (steps into) the condition handler, if any. 

!>rn^ are r f!! ng 1 the T ltipr ° CeSS debu Sging configuration to debug a multiprocess 

nnt f am i n 6 - 0glc f!. name DBG$PROCESS has the value MULTIPROCESS) 
note the following additional points: ’ 

‘ ,w!r EP C ° m “ and is executed in tha context of the visible process, but 
/rot n any 0t ^ er pro f esses that are not on hold (through a SET PROCESS 
/HOLD command) are also allowed to execute. If you use the DO command 

• ™ adcast a STEP command to one or more processes, the STEP command 
imS 6d m C ° nteXt ° f 6ach s P ecified P«x»s8 that is not on hold, but 

n llclseTl uf ° n h ° ld are als ° aIlowed to execute - 

all cases, a hold condition m the visible process is ignored. 

tl^SCT MOTEmmiSpprn'S in Whi0h “ “ ntinues de » ends whether 
MODE InT R p S INTERRUPT oommand was eatered - By default (SET 
nrnrpf* 1 executlon continues until it is suspended in any 

process. At that point, execution is interrupted in any other processes that 
were executing images, and the debugger prompts for input. 

Related commands: 


CALL 

DO 

EXIT 

GO 

SET BREAK/EXCEPTION 
SET MODE [NOJINTERRUPT 
SET PROCESS 
(SET,SHOW) STEP 
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Examples 


2 . 


3. 


DBG> show step _ . 

step type: source, nosilent, by line, 
over routine calls 

DBG> STEP 

stepped Co , «M0S-W) 

DBG> 

The SHOW STEP command identifies the defrn.lt 
rr 4 . QTFP mmmand. In this case, the ollii comman , 

at the beginning of line 4. 

DBG> STEP 5 

stepped to MAIN\%LINE 47 
47: SWAP(X,Y); 

DBG> 

beginning of line 47. 

dbg> step/into 

stepped to routine SWAP 

23: procedure SWAP (A,B: in out integer) is 

DBG> STEP 

stepped to MAIN\SWAP\%LINE 24 
24: TEMP: integer := 0; 

steppecfon^return from MAIN\SWAP\%LINE 24 to MAIN\SWAP\%LINE 29 
29: end SWAP; 

DBG> 

_ , . , , i „ qtttp/TNTO command causes the debugger to execute the 

nf e 0urce code The STEP/RETURN command causes the debugger to 
finish executing routine SWAP up to its RET instruction (that is up to the 
point just prior to transferring control back to the calling routine). 

4 DBG> set step instruction 
dbg> show step 

step type: source, nosilent, by instruction, 
over routine calls 

DBG> STEP 

stepped to SUB1\%LINE 26: MOVL 
26: Z:integer:=4; 

0BG> 

SHOW STEP command. The STEP command causes the debugger to exec 
SSL After the STEP command has completed execution is 

suspended at the first instruction (MOVL) of line 26 in modu 


S A #4,B A -20(FP) 
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Converts a memory address to a symbolic representation, if possible. 

Format 

SYMBOLIZE address-expression[, ... ] 

Parameters 


address-expression 

Sdcharacir eXPreSSi ° n *° ^ Symbtfed ' D ° »°‘ - asterisk (., 


Description 


ivih f ddress ia a static add ress, it is symbolized as the nearest preceding 
symbol name plus an offset. If the address is also a code address and a hue 

f °" nd »- -mberTi^dt the 


address is a register address, the debugger displays all symbols in all set 
modules that are bound to that register. The full pathname of each such symbol 
is displayed. The register name itself ("%R5", for example) is also displayed. 

mnH G l ad l re !f If 8 CaU Stack location in the ca ll frame of a routine in a set 
a rp d rii e V the f de ?u g ^ r searches for all symbols in that routine whose addresses 
°, tke Frame Pointer (FP) or the Stack Pointer (SP). The closest 

Aslborwb 6 PlU L an ° ffSet " as symbohzation of the 

ress. A symbol whose address specification is too complex is ignored. 

If the debugger can find no symbolization for the address, a message is displayed. 
Related commands: 


EVALUATE/ADDRESS 
SET MODE [NOJLINE 
SET MODE [NOJSYMBOLIC 
(SET,SHOW,CANCEL) MODULE 
SHOW SYMBOL 


Examples 


1. DBG> SYMBOLIZE %R5 
address PR0G\%R5: 

PR0G\X 

DBG> 

Sste X r a R5 Ple ^ 1<>Cal Variable X in routine PR OG is located in 


2. DBG> SYMBOLIZE %HEX 27C9E3 
address 0027C9E3: 

M0D5\X 

DBG> 


This command directs the debugger to treat the integer literal 27PQFR a 

SfiX’S* “ d «“« -ta- to a AtoSiSSj if 
possible. The address converts to the symbol X in module MOD5. 
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SYNCHRONIZE VECTOR_MODE 

Forces immediate synchronisation between the scalar and vector processors 


Applies to vectorized programs. 


Format 

SYNCHRONIZE VECTOR_MODE 


Description 


Examples 


and an MSYNC instruction. The effect is as follows. 

. t v.ritV.nt was caused by a vector instruction and was still pending 

exception handler (if one is available at that location in the program). 

instruction that was still being executed completes execution. 

„ , . qynOHRONIZE VECTOR MODE command is equivalent to issuing 

Entering the bYJNCHKUiNi^ vn. - . , r02Tam a t which execution 

SYNC and MSYNC instructions at the location in the progra 

is suspended. 

By default, the debugger does hot force synchroni Z ationbet^M. the Ka ar 
and vector processors during program execution (SET VECTOK-MUD 
NOSWCHRONIZED). Use the SET VECTORJMODE SYNCHRONIZED 
command to force such synchronization. 

Related commands: 

SET VECTORJMODE [NO]SYNCHRONIZED 
SHOW VECTORJMODE 


1 dbg> synchronize vector_mode , . 

%DEBUG-I-SYNCREPCOM, Synchronize reporting coraplet 
DBG> 

ThA SYNCHRONIZE VECTOR MODE command forces immediate 

between the sc'alar and vector processors. In this example, 
the diagnostic message indicates that the synchronization operationhas 
compS and that ll pending vector exceptions have been delivered and 

reported. 


CD-264 




Debugger Command Dictionary 
SYNCHRONIZE VECTOR_MODE 




DBG> STEP O 

stepped to .MAIN.\SUB\%LINE 99 
99: _ WDIVD V1,V0,V2 

DBG> STEP 0 

stepped to .MAIN.\SUB\%LINE 100 
100: CLRL R0 

DBG> EXAMINE/FLOAT %V2 © 

0\%V2 


[0]: 13.53400 

[1] : Reserved operand, encoded 

[2] : 247.2450 


as floating divide by zero 


DBG> SYNCHRONIZE VECTOR MODE O 

oSYSTEM F-VARITH, vector arithmetic fault, summary=00000002, 
hr ._, „ k ,, roask=00000004, PC=000002E1, PSL=03C00010 

oreak on unhandled exception preceding .MAIN.\SUB\%LINE 100 
iu u: CLRL R0) 

DBG> 

The comments that follow refer to the callouts in the previous example: 

0 J WTWn C °™ ma . nd sus P ends Program execution on line 99, just before 
“S?*"® is executed. Assume that, in this example, the 
instruction will trigger a floating-point divide-by-zero exception. 

0 “ P C0I ? mand execute s the WDIVD instruction. Note, however, 
program eXCeptl ° n 1S not dehvered at this point in the execution of the 

i^le^fdisplays a decoded exception message 

noint S K° f he destmatlon register, V2. This confirms that a floating- 
point divide-by-zero exception was triggered and is pending delivery. 

dTlive^Tm 0 ^ VECTOE - MODE C0mma ” d «"«» ‘he immediate 
delivery of the pending vector exception. 


0 


O 
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TYPE 


Displays lines of source code. 


Format 

TYPE [[module-name\]line-num[:line-num] 

[,[module-name\]line-num[:line-num][, .. • ]] 


Parameters 


toert a bacMash (\ ) between the module name and the hne numbers. 

H you do not specify a module ^me ,£££'££,% 

IcOPE^mmato tod Z™ lines for display. If you specif 
“ ZTh list with the SET SCOPE command, the debugger searches for 
souZhnes only in the module associated with the first named scope. 

53 C a compiler-generated line number (a number used to label a source 
language statement or statements). 

If you specify a single line number, the debugger displays the source cod 
corresponding to that line number. 

corresponding to that range of hne numbers, 
largest line number in the module. 

After displaying a single line of source code, you can display the nextlin ®°|’ 
, w j i bv entering a TYPE command without a hne number that is, y 
^ a TOE ”ZZni and then pressing the Return key. You can then 
*e next line and successive lines by repeating this sequence, in effect, 
rp.adiner through your source program one hne at a time. 


Description 


imeldeZZenerated by the compiler. They appear in a compfier-generated 
ting and in a screen-mode source display. 

t. Then use the SET MODULE command, if necessary. 
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Examples 


Debugger Command Dictionary 

TYPE 


specified and any surrounding lines that fit in the display iSdndow. 
Related commands: 

EXAMINE/SOURCE 

SET (BREAK,TRACE,WATCH)/[NO]SOURCE 
SET MODE [NOJSCREEN 
(SET,SHOW,CANCEL) SCOPE 
SET STEP [NOJSOURCE 
STEP/[NO]SOURCE 


1. DBG> type 160 
module COBOLTEST 

160: START-IT-PARA. 

DBG> TYPE 
module COBOLTEST 

161: MOVE SCI TO ESO. 

DBG> 


^ COmmand d Mays 160, using the current 
cope to locate the module containing that line number The second TYPF 

™l: ntered With0Ut Specifyins “ line JlKS in 


2. DBG> TYPE 160:163 
module COBOLTEST 

START-IT-PARA. 

MOVE SCI TO ESO. 
DISPLAY ESO. 

MOVE SCI TO ESI. 

DBG> 


161 

162 

163 


This command displays lines 160 to 163 
module. 


using the current scope to locate the 


!. DBG> TYPE SCREEN_I0\7,22:24 

This command displays line 7 and lines 22 to 24 in module SCREENJO. 
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Debugger Command Dictionary 
WHILE 



WHILE 


Executes a sequence of commands while the language expression (Boolean 
expression) you have specified evaluates as true. 


Format 

WHILE Boolean-expression DO (command[; • • • ]) 


Parameters 


Boolean-expression 

Specifies a language expression that evaluates as 
in the currently set language. 


a Boolean value (true or false) 


Spedifies'a debugger command. If you specify more than one command, separate 
them with semicolons. 


Description 


The WHILE command evaluates a in *^^e^ language.^ 

-—- 

command- list until the expression is evaluated as lalse. 

If the Boolean expression is false, the WHILE command terminates. 


Related commands: 

EXITLOOP 

FOR 

REPEAT 


Example 

DBG> WHILE (X .EQ. 0) DO (STEP/SILENT) 

This command directs the debugger to keep stepping through the program until 
X no longer equals 0 (FORTRAN example). 
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Command Defaults 


This appendix lists the defaults associated with debugger commands. 


Command 

@file-spec 

CALL 

CONNECT 

DEFINE 

DEFINE/KEY 

DELETE/KEY 

DEPOSIT 


DISPLAY 


DO 

EDIT 


(ENABLE,DISABLE) AST 
EVALUATE 


Default 


For any field of the file specification that is not 
specified, the default is SYS$DISK:[ ]DEBUG COM lb 
change the default, use the SET ATSIGN command. 

passed by address (%ADDR). 
CALL/AST/N OSAVE_VECTOR_STATE 

If no process is specified, the CONNECT command 
rings any processes that are waiting to connect to the 
debugging session under debugger control. 

DEFINE/ADDRESS 

DEFINE/KEY/ECHO/NOIF STATE/NOLOCK STATF 
/LOG/NOSET_STATE/NOTERMINATE " 


DELETE/KEY/LOG/NOSTATE 


anguage expressions are interpreted according to the 
currently set language. Address expressions that are 
associated with compiler generated types are treated 

tre a °ti ng u at ° ther address expressions are 
treated as having the type longword integer. 

mSP^Y/DYNAMIC/NOMARK CHANGE/POP when 

applied to an existing display. The current display 
kind, window, and size remain unchanged. 

DISPLAY/DWAIVUC/POP/SKE; 64 when creating 
a display. The default window is either HI or H2 
alternating between these two with each newlv created 
display. The default display kind is "outputs 

DO/PROCESS=* 

EDIT/NOEXIT. The default is to invoke the VAX 
Language-Sensitive Editor (LSE) in a spawned 
subprocess. This can be changed with a SET EDITOR 
command. The default source file to be edited is the 
We whose source code appears in the current source 
dl , S P lay ;, T1 J e default position of the editing cursor is 
either the beginning of the line that is centered in 
the current source display, or the start of line 1 if the 
editor was set to /NOSTART_POSITION. 

ENABLE AST 


Language expressions are interpreted 
currently set language. 


according to the 
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Command Defaults 


Command 

EXAMINE 

EXPAND 

EXTRACT 

MOVE 

SCROLL 

SEARCH 


SELECT 
SET ATSIGN 
SET BREAK 

SET DEFINE 
SET EDITOR 
SET IMAGE 
SET KEY 
SET LANGUAGE 

SET LOG 
SET MARGINS 

SET MAX_SOURCE_FILES 
SET MODE 

SET OUTPUT 

SET PROCESS 
SET PROMPT 


SET RADIX 


Default 


The contents of program locations that are associated 
with Compiler generated type are interpreted and 
Splayed accordLg to that type. The contents of other 
fifons are interpreted and displayed as longword 
integers. 

EXPAND/DOWN or /UP: 1 line. 

EXPAND/LEFT or /RIGHT: 1 column. 

If vou specify /SCREENJLAYOUT, the default output 
is SYS$DISK:[ IDBGSCraERCOR Otherw^e 
the default output file is SYS$DISK.[ ]DEBUG. 1X1. 

MOVE/DOWN or /UP: 1 line. 

MOVE/LEFT or /RIGHT: 1 column. 

SCROLL/DOWN or /UP: 3/4 of window height. 
SCROLL/LEFT or /RIGHT: 8 columns. 

SEARCH/NEXT/STRING. If no module name is 
specified the debugger uses the current scope to find a 
module and searches that module for an occurrence of 
the string. The current scope is that established by a 
previous SET SCOPE command, or the PC scope if no 
SET SCOPE command was entered Also, ^ 5 ? string 
is specified, the string specified in the last SEARCH 
command, if any, is used. 

SELECT/SCROLL 

SET ATSIGN SYS$DISK:[ 1DEBUG.COM 
SET break/into/jsb/share/system 
/NOSILENT/SOURCE 
SET DEFINE ADDRESS 

SET EDITOR/NOSTARTJPOSITION 
The current image is the main image. 

SET KEY/STATE=DEFAULT 

The default language is the language of the module 
that contains the image transfer address (mam 
program). 

SET LOG SYS$DISK:[ 1DEBUG.LOG 

SET MARGINS 1:255 (left margin: 1, right margin: 

255) 

SET MAX_SOURCE_FILES 5 

SET MODE DYNAMIC, NOG_FLOAT, KEYPAD, 

LINE, NOOPERANDS, NOSCREEN, NOSEPARATE, 
SCROLL, SYMBOLIC 

SET OUTPUT NOLOG, NOSCREEN_LOG, 
TERMINAL, NOVERIFY 
SET PROCESS/VISIBLE 
SET PROMPT/NOPOP "DBG> ". 

lE¥“p^KSoro^“uFFIX.PROCESS_NUMBEE 

"DBG_" 

For all languages except BLISS and MACRO: SET 
RADIX DECIMAL. For BLISS and MACRO. SE1 
RADIX HEXADECIMAL. 
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Command Defaults 


Command 


SET SCOPE 


SET SEARCH 
SET SOURCE 

SET STEP 
SET TERMINAL 

SET TRACE 
SET TYPE 


SET VECTOR_MODE 
SET WATCH 

SPAWN 

STEP 

TYPE 


Default 


he debugger looks up a symbol specified without a 
path name prefix according to the scope search list 

u ■; ',„ here n 1S the number of calls in the 
call stack) If the symbol is not found, the debugger 
searches the run-time symbol table, then the global 
symbol table if necessary. 

SET SEARCH NEXT, STRING 
tWnlffif Ching I° r 5 S0U , rce file > the debugger uses 

SISt') " th “ 18 S “ red " the 

SET STEP SOURCE, NOSILENT, OVER, LINE 
Thevalues of /PAGE and /WIDTH default to those set 

tbP T?PT (See i h ^ DCL Dictionary or enter 
the DCL command HELP SET TERMINAL). 

/sotrot CE/INT0/JSB/SH ^ e/system /N0sile nt 

The default type for program locations that are 
assocmted with a compiler generated type is that 

integer default type for other locati °ns is longword 
SET VECTOR_MODE NOSYNCHRONIZED 

variables: SET WATCH/NOSILENT 
/oUUKCE. For nonstatic variables* SET WATfPT 

/NOSILENT/OVER/SOURCE. 

SPAWN/WAIT 

STEP/OVER/LINE 

If no module name is specified, the debugger uses 
the current scope to find a module and searches 
that module for source lines for display. The current 
scope is that established by a previous SET SCOPE 
command, or the PC scope if no SET SCOPE command 
was entered. Also, if no line is specified after a 
single source line has been displayed with the TYPE 
command, the next line in that module is displayed by 
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B.1 


When you invoke the debugger, certain predefined functions (commands 
quences of commands, and command terminators) are assigned to keys on 
e numeric keypad, to the right of the main keyboard. By using these kevs 
you can enter certain commands with fewer keystrokes than if you wereVtype 
them at the keyboard. For example, pressing the comma key ( ) on the keypad 
IS equivalent to typing GO and then pressing the Return key Terminals and 
workstations that have an LK201 keyboard have addition?proi™mible kevs 
mpared to those on VT100 keyboards (for example, “Help” or “Remove”) and 
some of these keys are also assigned debugger functions. Kem ^e ), and 

To use function keys, keypad mode must be enabled (SET MODE KEYPAD) 
eypad mode is enabled when you invoke the debugger. If you do not want 
kevnad fo^f Tf^^’ per J a P s because the program being debugged uses the 
NOKEWAD command. 311 ^ m ° de by entering the SET MODE 

identifiS ad key functi ° ns that are Predefined when you invoke the debugger are 
identified in summary form in Figure B-l. Table B-l, Table B-2 Table B-3 

and Table B-4 identify all key definitions in detail. Most keys are used for 
manipulating screen displays in screen mode. To use screen mode commands vou 
must first enable screen mode by the PF3 key (SET MODE SCREEN). In screen 
mode, to re-create the default layout of various windows, press the keypad kev 
sequence BLUE-MINUS (PF4 followed by the MINUS key (-)). y 

To use the keypad keys to enter numbers rather than debugger commands enter 
the command SET MODE NOKEYPAD. mmanas, enter 

DEFAULT, GOLD, BLUE Functions 

A given key typically has three predefined functions: 

ffiEESfc^ ered by PreSSin§ 1116 8ivm key by itod£ This a* 

A second function is entered by pressing and releasing the PF1 key and then 

E532ZT keyThis is the G0LD function ’ because 

A third function is entered by pressing and releasing the PF4 key and then 
the BLUE key VGn ^ ^ ^ BLUE function ’ because PF4 is also called 









Predefined Key Functions 

B.l DEFAULT, GOLD, BLUE Functions 


Figure B-1 Keypad Ke, Functions Predefined b, the Debugger-Co mmand Inte rface 


r F17 1 

DEFAULT 

(SCROLL) 

l 

F18 1 

MOVE 

F19 

EXPAND 
(EXPAND +) 

F20 ^ 

CONTRACT 
(EXPAND -) 

_ J 

r pfi 

GOLD 

GOLD 

GOLD 

PF2 

HELP DEFAULT 
HELP GOLD 
help BLUE 

PF3 1 

SET MODE SCREEN 
SET MODE NOSCR 
disp/generate 

PF4 ^ 

BLUE 

BLUE 

BLUE 

7 

DISP SRC,INST,OUT 
DISP INST,REG,OUT 
DISP 2 SRC, 2 INST 

ft \ 

SCROLL/UP 

SCROLL/TOP 

SCROLL/UP... 

C J 

9 

DISPLAY next 

SET PROC next 
DISP 2 SRC 

DISP next at FS 

DISP SRC, OUT 

SCROLULEFT 

SC ROLL/LEFT:255 
SCROLL/LEFT... 

5 

EX/SOU .0\%PC 
SHOW CALLS 
SHOW CALLS 3 

ft \ 

SCROLL/RIGHT 

SCROLURIGHT:255 

SCROLL/RIGHT... 

_> 

> 

GO 

SEUSOURCE next 
SEL/INST next 

1 


3 

ENTER 

EXAMINE 

SCROLL/DOWN 

SEL SCROLL next 


EXAM A (prev) 

SCROLL/BOTTOM 

SEL OUTPUT next 


DISP 3 SRC, 3 INST 

SCROLL/DOWN... 

DISP 3 SRC 



> 


ENTER 

0 

STEP 

RESET 


STEP/INTO 

RESET 


STEP/OVER 

RESET 


\_- 



J 


"MOVE" 


MOVE/UP 
MOVE/UP :999 
MOVE/UP .5 


MOVE/LEFT 
MOVE/LEFT :999 
MOVE/LEFT:10 


MOVE/RIGHT 

MOVE/RIGHT:999 

MOVE/RIGHT:10 


MOVE/DOWN 
MOVE/DOWN :999 
MOVE/DOWN :5 


/T 


"EXPAND" 




EXPAND/UP 
EXPAND/UP :999 
EXPAND/UP:5 


/f 


expand/left 

EXPAND/LEFT :999 
EXPAND/LEFT:10 


/f 


expand/right 

EXPAND/RIGHT :999 

expand/right-.io 


EXPAND/DOWN 
EXPAND/DOWN.999 
EXPAND/DOWN:5 




LK201 Keyboard: 

Press 

F17 

F18 

F19 

F20 

VT-100 Keyboard: 

Type 

SET KEY/STATE=DEFAULT 
SET KEY/STATE=MOVE 
SET KEY/STATE=EXPAND 
SET KEY/STATE=CONTRACT 


Keys 2,4,6,8 

SCROLL 

MOVE 

EXPAND 

CONTRACT 


Keys 2,4,6,8 

SCROLL 

MOVE 

EXPAND 

CONTRACT 


"CONTRACT 1 


EXPAND/UP:-1 

EXPAND/UP.-999 

EXPAND/UP-5 


/f 


">S 


EXPAND/LEFT-1 
EXPAND/LEFT.-999 
EXPAND/LEFT :-10 




expand/right-.-i 

EXPAND/RIGHT :-999 
EXPAND/RIGHT :-10 


■v 


EXPAND/DOWN :-1 
EXPAND/DOWN :-999 
EXPAND/DOWN.-5 


ZK-0956A-GE 
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d i nrr a • tl rec,e ' ,n ed Key Functions 
B.1 DEFAULT, GOLD, BLUE Functions 

S' 

=£=sssa«~“ 

All command sequences assigned to keypad keys are terminated (executed 
unme lately) except for the BLUE functions of keys KP2, KP4 KP6 and KP8 

to S™“re bTt^ “ e Wi ‘ h a “togas’“ f 

RFTnPM B p _L T T 1 the command > supply a parameter and then press 
RETURN. For example, to scroll down 12 lines, do the following: 

1. Press the PF4 key. 

2. Press keypad key KP2. 

3. Type :12 at the keyboard. 

4. Press the Return key. 

B.2 Key Definitions Specific to LK201 Keyboards 

VTl'oO^vh™^ th! “ ft Spe f flc 40 LK201 keyboards and do not appear on 
VT100 keyboards. For each key, the table identifies the equivalent command and 

£y 0 7ke& equivalen ‘ keypad key ^ « - if you do'not W 2* 


Table B-l 

LK201 Key 

F17 
FI 8 
FI 9 
F20 
Help 

Next Screen 
Prev Screen 
Remove 
Select 


Key Definitions Specific to LK201 Keyboards 

Comma nd Sequence Invoked 

SET KEY/STATE=DEFAULT 
SET KEY/STATE=MOVE 
SET KEY/STATE=EXPAND 
SET KEY/STATE=CONTRACT 
HELP KEYPAD SUMMARY 
SCROLL/DOWN 
SCROLL/UP 

DISPLAY/REMOVE %CURSCROLL 
SELECT/SCROLL %NEXTSCROLL 


None 

None 

None 

None 

None 

KP2 

KP8 

None 

KP3 


B.3 Keys That Scroll, Move, Expand, Contract Displays 

diLIf™) 1 ' k«yP»d keys KP2, KP4, KP6, and KP8 scroU the current scrolling 
By press,ngkeyrFTfpiQ “ TS? ° n (d °' m ’ lef *' right ’ and up ' respectively). 

™ °^e 0N ^ 8 Tat T ^^«toX d ^%rtTkeys 

left, and so on. ^ CO F* 

Z be - d -fto ” contract the current Fta” B 7 

S tey VT 1 OCMceyboards are 
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K^KoTMove, Expand, Contract Displays 

To scroll, move, expand, or contract a display, proceed as fol 

1 p r ess key KP3 repeatedly, as needed, to select the current scrolling sp ay 
from the display list. 

2 Press key F17, F18, F19, or F20 to put the keypad in the DEFAULT (scro ), 
MOVE, EXPAND, or CONTRACT state, respectively. 

o T> Wc rrpo KP4 KP6 and KP8 to do the desired function. Use the 
' m (GOLD) and PF4 (BLUE) keys to control the amount of scrol mg or 

movement. 


Table B -2 Keys That Change the Key State 


Key 


Description 


PF1 
PF4 
FI 7 

FI 8 
FI 9 
F20 


Invokes the GOLD function of the next key you press. 

Invokes the BLUE function of the next key you press. 

j. tyi 7FATTTT state enabling the scroll-display functions 

SmS 1 ™'S™ Ckeypadi/in the DEFAULT state when 
you invoke the debugger. 

Puts the keypad in the MOVE state, enabling the move-display functions o 
keys KP2, KP4, KP6, and KP8. 

Puts the keypad in the EXPAND state, enabling the expand-display functions 
of keys KP2, KP4, KP6, and KP8. 

Puts the keypad in the CONTRACT state enabling the contract-display 
functions of keys KP2, KP4, KP6, and KP8.__. 


If you have a VT100 keyboard, yo« 

to F20 by defining the key sequences GOLD-KrS ana dluc 

undefined) as shown below. With these defintttons pres^ng ^D-KPS puts the 

states (like cycling 

3 might want * store these key definitions tn a 

command procedure, such as your debugger initialization fi e. 

DEFINE/KEY/IF STATE=(GOLD,MOVE GOLD,EXPAND_GOLD,CONTRACT_GOLD)- 
^/TERMINATE KP9 "SET KEY/STATE=DEFAULT/NOLOG" 

DEFINE/KEY/IF STATE=(BLUE)- 
/TERMINATE KP9 "SET KEY/STATE=MOVE/NOLOG 
nFFTNF/KEY/IF STATE=(MOVE BLUE)- 
^/TERMINATE KP9 "SET KEY/STATE=EXPAND/NOLOG" 
nFFTNF/KEY/IF STATE=(EXPAND BLUE)- 

^/TERMINATE KP9 "SET KEY/STATE=CONTRACT/NOLOG" 
nFPTNE/KEY/IF STATE=(CONTRACT BLUE)- 
^/TERMINATE KP9 "SET KEY/STATE=DEFAULT/NOLOG" 

B.4 Online Keypad Key Diagrams 

n linta HFT p for the keypad keys is available by pressing the Help key and also 
the PF2 key, either by itself or with other keys (see Table B-3). You can ais 
the SHOW KEY command to identify key definitions. 
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Predefined Key Functions 
B.4 Online Keypad Key Diagrams 


Key Sequence 

Command Sequence Invoked 

Help 

HELP KEYPAD SUMMARY 

PF2 

HELP KEYPAD DEFAULT 

PF1-PF2 

HELP KEYPAD GOLD 

PF4-PF2 

HELP KEYPAD BLUE 

F18-PF2 

HELP KEYPAD MOVE 

F18-PF1-PF2 

HELP KEYPAD MOVE_GOLD 

F18-PF4-PF2 

HELP KEYPAD MOVE_BLUE 

F19-PF2 

HELP KEYPAD EXPAND 

F19-PF1-PF2 

HELP KEYPAD EXPAND_GOLD 

F19-PF4-PF2 

HELP KEYPAD EXPAND_BLUE 

F20-PF2 

HELP KEYPAD CONTRACT 

F20-PF1-PF2 

HELP KEYPAD CONTRACT.GOLD 

F20-PF4-PF2 

HELP KEYPAD CONTRACT_BLUE 


B.5 Debugger Key Definitions 

Table B-4 identifies all key definitions. 

Table B-4 Debugge r Key Definitions 
Key 


Shows a diagram of the keypad keys and 
summarizes each key’s function 

Shows a diagram of the keypad keys and 
their DEFAULT functions 

Shows a diagram of the keypad keys and 
their GOLD functions 

Shows a diagram of the keypad keys and 
their BLUE functions 

Shows a diagram of the keypad keys and 
their MOVE DEFAULT functions 

Shows a diagram of the keypad keys and 
their MOVE GOLD functions 

Shows a diagram of the keypad keys and 
their MOVE BLUE functions 

Shows a diagram of the keypad keys and 
their EXPAND DEFAULT functions 

Shows a diagram of the keypad keys and 
their EXPAND GOLD functions 

Shows a diagram of the keypad keys and 
their EXPAND BLUE functions 

Shows a diagram of the keypad keys and 
their CONTRACT DEFAULT functions 

Shows a diagram of the keypad keys and 
their CONTRACT GOLD functions 

Shows a diagram of the keypad keys and 
their CONTRACT BLUE functions 


KPO 


KPl 


State 

DEFAULT 

GOLD 

BLUE 

DEFAULT 

GOLD 


Command Invoked or Function 


STEP 

STEP/INTO 

STEP/OVER 

EXAMINE. Examines the logical successor of the 
current entity, if one is defined (the next location). 

EXAMINE a . Enables you to examine the logical 
predecessor of the current entity, if one is defined 
(the previous location). 

(continued on next page) 
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Predefined Key Functions 
B.5 Debugger Key Definitions 



BLUE 


KP2 


DEFAULT 

GOLD 

BLUE 


Displays three sets of predefined process^specific 

source and instruction displays, SRC_n and 
INST_n. These consist of source and instruction 
displays for the visible process at S2 and Rb2, 
respectively; source and instruction displays for the 
previous process on the process list at SI and RSI, 
respectively; and source and instructiondisplaysfor 
the next process on the process list at S3 and RS3, 
respectively. 

SCROLL/DOWN 

SCROLL/BOTTOM 

SCROLL/DOWN (not terminated). To terminate the 
command, supply the number of lines to be scrolled 


KP3 


KP4 


MOVE 

MOVE_GOLD 

move.blue 

EXPAND 

EXPAND_GOLD 

EXPAND_BLUE 

CONTRACT 

CONTRACT_GOLD 

CONTRACTJBLUE 

DEFAULT 

GOLD 

BLUE 


BLUE 

DEFAULT 

GOLD 

BLUE 

MOVE 

MOVE_GOLD 

move.blue 

EXPAND 


MOVE/DOWN 
MOVE/DOWN :999 
MOVE/DOWN :5 
EXPAND/DOWN 
EXPAND/DOWN :999 
EXPAND/DO WN:5 
EXPAND/DOWN :-l 
EXPAND/DOWN :-999 


EXPAND/DOWN :-5 

SELECT/SCROLL %NEXTSCROLL. Selects as the 
current scrolling display the next display in the 
display list after the current scrolling display. 

SELECT/OUTPUT %NEXTOUTPUT. Selects the 
next output display in the display list as the current 
output display. 

Displays three predefined process-specific source 
displays, SRC_n. These are located at SI, S2 and 
S3, respectively, for the previous, current (visible), 
and next process on the process list. 

SELECT/SOURCE %NEXTSOURCE. Selects the 
next source display in the display list as the current 
source display. 

SCROLL/LEFT 

SCROLL/LEFT:255 

SCROLL/LEFT (not terminated). To terminate the 
command, supply the number of lines to be scrolled 
(:«) or a display name. 

MOVE/LEFT 


MOVE/LEFT-.IO 

EXPAND/LEFT 

(continued on next page) 
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Predefined Key Functions 
B.5 Debugger Key Definitions 


Table B-4 (Cont.) Debugg er Key Definitions 
Key 


KP5 


EXPAND_GOLD 
EXEAND_BLUE 
CONTRACT 
CONTRACT_GOLD 
CONTRACT_BLUE 
DEFAULT 


EXPAND/LEFT:999 
EXPAND/LEFTrl 0 
EXPAND/LEFT:-1 
EXPAND/LEFT:-999 
EXPAND/LEFT:-10 

EXAMINE/SOURCE .%SOURCE_SCOPE\ %pc- 
EXAMINE/INST .%INST_SCOPE\%PC. In line 
(noscreen) mode, displays the source line and 
the instruction to be executed next. In screen 
mode, centers the current source display on the 
next source line to be executed, and the current 
instruction display on the next instruction to be 
executed. 


GOLD 

BLUE 

KP6 DEFAULT 

GOLD 
BLUE 

MOVE 

MOVE_GOLD 
MOVE_BLUE 
EXPAND 
EXPAND.GOLD 
EXPAND_BLUE 
CONTRACT 
CONTRACT_GOLD 
CONTRACT_BLUE 
KP7 DEFAULT 


GOLD 


SHOW CALLS 
SHOW CALLS 3 
SCROLL/RIGHT 
SCROLL/RIGHT:255 


- v ^luunatcuA iu terminate the 
command, supply the number of lines to be scrolled 
or a display name. 

MOVE/RIGHT 


MOVE/RIGHT:999 
MOVE/RIGHT.T 0 
EXPAND/RIGHT 
EXPAND/RIGHT:999 
EXPAND/RIGHT:10 
EXPAND/RIGHT:-1 
EXPAND/RIGHT:-999 
EXPAND/RIGHT:-10 


——* i jni, iisot AT Km OUT AT 

?RP. AT S6; SELECT/SCROLL/SOURCE 

SRC; SELECT/INST INST; SELECT/OUT OUT 
Displays the SRC, INST, OUT, and PROMPT 
displays with the proper attributes. 

DISPLAY INST AT LH1, REG AT RH1 OUT AT 
PROMPT AT S6; SELECT/SCROLMNST 
INST, SELECT/OUT OUT. Displays the INST 

attributes^' PROMPT dis P la ys with the proper 


(continued on next page) 
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Predefined Key Functions 
B.5 Debugger Key Definitions 


Table B-4 (Cont.) 

Key State 

BLUE 


Debugger Key Definitions 


Command Invoked or Function 


Displays two sets of predefined Process-specifie 
source and instruction displays, SRC_n ** nd 
INST_n. These consist of source and instruction 
disDlavs for the visible process at Q1 and Kyi, 
respectively, and source and instruction displaysYor 
the next process on the process list at Q2 and RQ2, 


KP8 DEFAULT 

GOLD 
BLUE 

MOVE 

MOVE_GOLD 

move.blue 

EXPAND 

EXPAND_GOLD 

expand_blue 

CONTRACT 
CONTRACT_GOLD 
CONTRACT_BLUE 
KP9 DEFAULT 

GOLD 

BLUE 


PF1 

PF2 

PF3 DEFAULT 


GOLD 

BLUE 

PF4 

COMMA DEFAULT 


SCROLL/UP 

SCROLL/TOP 

SCROLL/UP (not terminated). To terminate the 
command, supply the number of lines to be scrolle 
(:n) or a display name. 

MOVE/UP 

MOVE/UP:999 

MOVE/UP:5 

EXPAND/UP 

EXPANDAJP:999 

EXPAND/UP:5 

EXPAND/UP:-1 

EXPAND/UP:-999 

EXPAND AJP:-5 

DISPLAY %NEXTDISP. Displays the next display 
in the display list through its current window 
(removed displays are not included). 

SET PROCESS/VISIBLE %NEXT_PROCESS. 

Makes the next process in the process list the 
visible process. 

Displays two predefined process-specific so^ce 
displays, SRC_n. These are located at Q1 and Q2 
respectively, for the visible process and for the next 
process on the process list. 

See Table B-2. 

See Table B-3. 

SET MODE SCREEN; SET STEP NOSOURCE 
Enables screen mode and suppresses the output 
of source lines that would normally appear m th ® 
output display (since that output is redundant when 
the source display is present). 

SET MODE NOSCREEN; SET STEP SOURCE. 
Disables screen mode and restores the output o 
source lines. 

DISPLAY/GENERATE. Regenerates the contents of 
all automatically updated displays. 


See Table B-2. 
GO 


(continued on next page) 


B-8 












Predefined Key Functions 
B.5 Debugger Key Definitions 


Table B-4 (Cont.) Debugger Key Definitions 
Key" 


State 

GOLD 


BLUE 


Command Invoked or Function 


MINUS DEFAULT 


GOLD 

BLUE 


Enter 


PERIOD 

All states 

Next 

Screen 

(E6) 

DEFAULT 

Prev 

Screen 

(E5) 

DEFAULT 

Remove 

(E3) 

DEFAULT 

Select 

(E4) 

DEFAULT 

FI 7 


FI 8 


FI 9 


F20 


Ctrl/W 


Ctrl/Z 



SELECT/SOURCE %NEXT_SOURCE. Selects the 
next source display in the display list as the current 
source display. 

SELECT/INSTRUCTION %NEXTINST. Selects the 
next instruction display in the display list as the 
current instruction display. 

DISPLAY %NEXTDISP AT SI 2345, PROMPT AT 
S6; SELECT/SCROLL %CURDISP. Displays the 
next display in the display list at essentially full 
screen (top of screen to top of PROMPT display). 
Selects that display as the current scrolling display. 
Undefined 

DISPLAY SRC AT HI, OUT AT S45 PROMPT AT 
.^’ ^^DCT/SGROLUSOURGE SRC; SELECT 
/OUT OUT. Displays the SRC, OUT, and PROMPT 
displays w!th the proper attributes. This is the 
default display configuration. 

Enabies you to enter (terminate) a command. Same 
effect as Return. 

Cancels the effect of pressing state keys which do 
not lock the state, such as GOLD and BLUE. Does 
not affect the operation of state keys which lock the 
state, such as MOVE, EXPAND, and CONTRACT. 

SCROLL/DOWN 


SCROLL/UP 

DISPLAY/REMOVE %CURSCROLL. Removes the 
current scrolling display from the display list. 

SELECT/SCROLL %NEXTSCROLL. Selects as the 
current scrolling display the next display in the 
display list after the current scrolling display. 

See Table B-2. 

See Table B—2. 

See Table B-2. 

See Table B-2. 

DISPLAY/REFRESH 

EXIT 
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Screen Mode Reference Information 


1 Te™,r d refer6nCeinfo ™ at “’ n ”*** *»«"«-node. 

• Display kinds 

• Display attributes 

• Predefined displays 

• Screen-related built-in symbols 

Screen dimensions and predefined windows 


C.1 Display Kinds 


The DISPLAY command accepts these display-kind keywords and parameters: 


DO ( command[; . .. ]) 


INSTRUCTION 


INSTRUCTION ( command ) 


OUTPUT 


REGISTER 

SOURCE 


Specifies an automatically updated output display. 

. e commands are executed in the order listed each 
time the debugger gains control. Their output forms 
the contents of the display. If you specify more than 
one command, they must be separated by semicolons. 

Specifies an instruction display. If selected as the 
current instruction display with the SELECT 
INSTRUCTION command, it displays the output 
trom subsequent EXAMINE/INSTRUCTION 
commands. 

Specifies an automatically updated instruction 
The command specified must be an 
EXAMINE/INSTRUCTION command. The 
instruction display is updated each time the 
debugger gains control. 

Specifies an output display. If selected as the 
current output display with the SELECT/OUTPUT 
command, it displays any debugger output that is not 
directed to another display. If selected as the current 
input display with the SELECT/INPUT command 
it echoes debugger input. If selected as the current 
error display with the SELECT/ERROR command, it 
displays debugger diagnostic messages. 

Specifies an automatically updated register display, 
control ^ 1S updated eac h time the debugger gains 

Specifies a source display. If selected as the current 
source display with the SELECT/SOURCE command 
it displays the output from subsequent TYPE or 
EXAMINE/SOURCE commands. 
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C.1 Display Kinds 


SOURCE (< command ) 


Specifies an automatically updated somcedisp y. 
The command specified must be a TYPh or 
EXAMINE/SOURCE command. The source display 
is updated each time the debugger gams control. 


C.2 Display Attributes 


Thp SFLECT command assigns an attribute to a display according to tb® 

qualifier used with that command^ The you can 

SELECT command qualifiers, its effect, and the aisp y 
assign that attribute. 


/ERROR 


/INPUT 


/INSTRUCTION 


/OUTPUT 


/PROGRAM 


/PROMPT 


Selects the specified display as the current error 
any subsequent debugiei diagnest.c message $£%%%% no 
rriiiQf hp either an output display or the rrtOMr i aispiay. n 
Ssp!ay is lpSi selects the PROMPT display as the current 

error display. 

Selects the specified display as the current input^lay. EAoes 
anv subsequent debugger input in that display. It must be an 
output display. If no display is specified, unselects the current 
input dispfayf debugger input is not echoed to any display. 

Selects the specified display as the “^^^StToN 
Directs the output of any subsequent EXAMINE/INSTRU 01 UJiN 

command to that display. It must be an 

m TTF-COMMA keypad sequence selects the next instruction 
Splay inSdiapS list *> «» currant instruction display If no 
display is specified, unselects the current instruction display, no 
display has the instruction attribute. 

Selects the specified display as the current output display. Directs 
anv subsequent debugger output to that display, except where a 
partfculaXpe of output is being directed to another disp ay (such 
as diagnostic messages going to the current error di s P ay). 
specified display must be either an output display or the PROMPi 
display The GOLD-KP3 keypad key sequence selects the next 
output display in the display list as the current output display. If 

™ SfpS f the PR0MPT display 85 “ r ' ent 

output display. 

Selects the specified display as the current program display 
Tries to force any subsequent program input or output to that 
display Currently, only the PROMPT display can be specified 
If no display is specified, unselects 

program output is no longer forced to the PROMri display. 

Selects the specified display as the current prompt di 
the debugger prompts for input. Currently, only the PROM 
display c!n be specified. You cannot unselect the PROMPT 
display. 
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C.2 Display Attributes 


SELECT 

Qualifier 

Description 

/SCROLL 

Selects the specified display as the current scrolling display. 
Makes that display the default display for any subsequent 
SCROLL, MOVE, or EXPAND command. You can specify any 
display (however, note that the PROMPT display cannot be 
scrolled). The /SCROLL qualifier is the default if you do not 
specify a qualifier with the SELECT command. The KP3 key 
selects as the current scrolling display the next display in the 
display list after the current scrolling display. If no display is 
specified, unselects the current scrolling display: no display has 
the scroll attribute. 

/SOURCE 

Selects the specified display as the current source display. Directs 
the output of any subsequent TYPE or EXAMINE/SOURCE 
command to that display. It must be a source display. The BLUE- 
3 keypad key sequence selects the next source display in the 
display list as the current source display. If no display is specified, 
unselects the current source display: no display has the source 
attribute. 

By default, when you invoke screen mode, the predefined displays are selected for 
attributes as follows: 

Attribute 

Predefined Display 

Error 

PROMPT 

Input 

no display selected 

Instruction 

no display selected 

Output 

OUT 

Program 

PROMPT 

Prompt 

PROMPT 

Scroll 

SRC 

Source 

SRC 


C.3 Predefined Displays 

This section summarizes the properties of the predefined displays SRC, OUT 
PROMPT, INST and REG. 

C.3.1 SRC (Source Display) 

SRC is an automatically updated source display. It shows the source code of the 
module being debugged, if that source code is available. The arrow points to the 
source line corresponding to the current PC value (where execution is suspended). 

The default characteristics of the SRC display are the following: 

Display kind source (examine/source .%source_scope\%pc) 

Attributes scroll, source 

Position HI 

Size 64 lines 

Dynamic yes 
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C.3 Predefined Displays 


%SOURCE_SCOPE is a built-in scope that has the following properties: 

• By default %SOURCE_SCOPE denotes scope 0, which is the scope of the 
routine where execution is currently suspended. 

• If you have reset the scope search list relative to the call stack by means 
of the SET SCOPE/CURRENT command, %SOURCE_SCOPE denotes the 
current scope specified (the scope of the routine at the start of the search list). 

• If source code is not available for the routine in the current scope, 
%SOURCE_SCOPE denotes scope N, where N is the first level down the 
call stack for which source code is available. 

When displaying source lines that are not associated with the module where 
execution is suspended, the debugger issues the following message. 

%DEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC. 

Displaying source in a caller of the current routine. 

C.3.2 OUT (Output Display) 

OUT shows all debugger output that is not directed to another display. 

The default characteristics of the OUT display are the following: 

Display kind output 

Attribute output 

Position S45 

Size 100 lines 

Dynamic yes 

C.3.3 PROMPT (Prompt Display) 

PROMPT is the display in which the debugger prompts for input and, by default, 
forces program output and prints debugger diagnostic messages. 

PROMPT has different properties and restrictions than other displays. This is to 
eliminate possible confusion when manipulating that display: 

• You cannot hide, remove, permanently delete, or scroll PROMPT. 

• You can contract PROMPT down to 2 lines. You cannot contract PROMPT 
horizontally. 

The default characteristics of the PROMPT display are the following: 


Display kind 
Attributes 

Position 

Size 

Dynamic 


program 

error, prompt, program (no other display can have the prompt or 
program attributes) 

S6 

not applicable (PROMPT is not scrollable) 
yes 
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C.3 Predefined Displays 


C.3.4 INST (Instruction Display) 

INST is an automatically updated instruction display. It shows the instruction 
stream of the routine being debugged. The instructions displayed are decoded 
from the image being debugged. The arrow points to the instruction at the 
current PC value. 

The default characteristics of the INST display are the following: 

Display Kind Instruction (EXAMINE/INSTRUCTION ,%INST_SCOPE\%PC) 

Attributes none 

Position HI, removed 

Size 64 lines 

Dynamic yes 

%INST_SCOPE is a built-in scope that has the following properties: 

• By default %INST_SCOPE denotes scope 0, which is the scope of the routine 
where execution is currently suspended. 

• If you have reset the scope search list relative to the call stack by means of 
the SET SCOPE/CURRENT command, %INSTJ3COPE denotes the current 
scope specified (the scope of the routine at the start of the search list). 

C.3.5 REG (Register Display) 

REG automatically shows the current values, in hexadecimal format, of the VAX 
general registers (R0 to Rll, AP, FP, SP, and PC), the four condition code bits 
(C,V, Z, and N) of the processor status longword (PSL), and as many of the top 
call stack values as can be displayed in the window. 

The register values displayed are for the routine in which execution is currently 
suspended. The values are updated whenever the debugger takes control. Any 
changed values are highlighted. 

The default characteristics of the REG display are the following: 

Display Kind Register 

Attribute none 

Position RH1, removed 

Size 64 lines 

Dynamic yes 

If the register window is resized, the debugger automatically reformats the 
displayed information to adapt to the new window size. 

Display REG does not display the current values of the VAX vector registers. To 
display data contained in vector registers or vector control registers in screen 
mode, use a DO display. (See Section 7.6.1.) 

C.4 Screen-Related Built-In Symbols 

The following built-in symbols are available for specifying displays and screen 
parameters in language expressions: 

• %SOURCE_SCOPE—To display source code. %SOURCE_SCOPE is described 
in Section C.3.1. 

• %INST_SCOPE—To display instructions. %INST_SCOPE is described in 
Section C.3.4. 
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C.4 Screen-Related Built-In Symbols 


• %PAGE, % WIDTH—To specify the current screen height and width. 

• %CURDISP, %CURSCROLL, %NEXTDISP, %NEXTINST, %NEXTOUTPUT, 
%NEXTSCROLL, %NEXTSOURCE—To specify displays in the display list. 

C.4.1 Screen Height and Width 

The built-in symbols %PAGE and %WIDTH return, respectively, the current 
height and width of the terminal screen. These symbols can be used in various 
expression, such as for window specifications. For example, the following 
command defines a window named MIDDLE that occupies a region around 
the middle of the screen: 

DBG> SET WINDOW MIDDLE AT (%PAGE/4,%PAGE/2,%WIDTH/4,%WIDTH/2) 


C.4.2 Display Built-In Symbols 

Each time you refer to a specific display with a DISPLAY command, the display 
list is updated and reordered, if necessary. The most recently referenced display 
is put at the tail of the display list, since that display is pasted last on the 
pasteboard (the display list can be identified by entering a SHOW DISPLAY 
command). 

You can use display built-in symbols to specify displays relative to their positions 
in the display list. These symbols, listed as follows, enable you to refer to 
displays by their relative positions in the list instead of by their explicit names. 
The symbols are used mainly in keypad key definitions or command procedures. 

Display symbols treat the display list as a circular list. Therefore, you can enter 
any commands that use display symbols to cycle through the display list until 
you reach the display you want. 


%CURDISP 

%CURSCROLL 

%NEXTDISP 

%NEXTINST 

%NEXTOUTPUT 

%NEXTSCROLL 


The current display. This is the display most recently referenced 
with a DISPLAY command—the least occluded display. 

The current scrolling display. This is the default display for the 
SCROLL, MOVE, and EXPAND commands, as well as for the 
associated keypad keys (KP2, KP4, KP6, and KP8). 


The next display in the list after the current display The next 
display is the display that follows the topmost display Because 
the display list is circular, this is the display at the bottom of the 
pasteboard—the most occluded display. 


The next instruction display in the display list after the current 
instruction display. The current instruction display is the 
display that receives the output from EXAMINE/INSTRUCTION 
commands. 


The next output display in the display list after the current output 
display. An output display receives debugger output that is not 
already directed to another display. 


The next display in the display list after the current scrolling 
display. 


%NEXTSOURCE The next source display in the display list after the current source 
display. The current source display is the display which receives the 
output from TYPE and EXAMINE/SOURCE commands. 
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C.5 Screen Dimensions and Predefined Windows 


C.5 Screen Dimensions and Predefined Windows 

On a VT-series terminal, the screen consists of 24 lines by 80 or 132 columns. On 
a workstation, the screen is larger in both height and width. The debugger can 
accommodate screen sizes up to 100 lines by 255 columns. 

The debugger has many predefined windows that you can use to position displays 
on the screen. The SHOW WINDOW command identifies all predefined and user 
defined windows. The predefined windows are expressed in terms of fractions 
of the screen dimensions (for example, quarters, halves, and so on). Therefore, 
the positions and dimensions of the predefined windows that are indicated by the 
SHOW WINDOW command are adjusted for the screen dimensions. 

In addition to the full height and width of the screen, the predefined windows 
include all possible regions that result from dividing the screen vertically into 
halves, thirds, quarters, sixths, and eighths, and horizontally into left and right 
halves. 

The following conventions apply to the names of predefined windows. The 
prefixes L and R denote left and right windows, respectively. Other letters denote 
the full screen (FS) or fractions of the screen height (H: half, T: third, Q: quarter, 
S: sixth, E: eighth). The trailing numbers denote specific fractions of the screen 
height, starting from the top. For example: 

• Windows Tl, T2, and T3 occupy the top, middle and bottom thirds of the 
screen, respectively. 

• Window RH2 occupies the right bottom half of the screen. 

• Window LQ23 occupies the left middle two quarters of the screen. 

• Window S45 occupies the fourth and fifth sixths of the screen. 

The horizontal boundaries (start-column, column-count) of the predefined 
windows for the default terminal screen width of 80 columns are as follows: 

• Left hand windows: (1,40) 

• Right hand windows: (42,39) 

The vertical boundaries (start-line, line-count) of the predefined windows for the 
default terminal screen height of 24 lines are as follows: 


Window Name 

Start-Line, Line-Count 

Window Locati< 

FS 

(1,23) 

Full screen 

HI 

(1,11) 

Top half 

H2 

(13,11) 

Bottom half 

Tl 

(1,7) 

Top third 

T2 

(9,7) 

Middle third 

T3 

(17,7) 

Bottom third 

Q1 

(1,5) 

Top quarter 

Q2 

(7,5) 

Second quarter 

Q3 

(13,5) 

Third quarter 

Q4 

(19,5) 

Bottom quarter 

SI 

(1,3) 

Top sixth 
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C.5 Screen Dimensions and Predefined Windows 


Window Name 

Start-Line, Line-Count 

Window Location 

S2 

(5,3) 

Second sixth 

S3 

(9,3) 

Third sixth 

S4 

(13,3) 

Fourth sixth 

S5 

(17,3) 

Fifth sixth 

S6 

(21,3) 

Bottom sixth 

El 

(1,2) 

Top eighth 

E2 

(4,2) 

Second eighth 

E3 

(7,2) 

Third eighth 

E4 

(10,2) 

Fourth eighth 

E5 

(13,2) 

Fifth eighth 

E6 

(16,2) 

Sixth eighth 

E7 

(19,2) 

Seventh eighth 

E8 

(22,2) 

Bottom eighth 
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Built-In Symbols and Logical Names 


This appendix identifies all of the debugger built-in symbols and logical names. 

D.1 SS$_DEBUG Condition 

SS$_DEBUG (defined in SYS$LIBRARY:STARLET.OLB) is a condition you can 
signal from your program to invoke the debugger. Signaling SS$_DEBUG from 
your program is equivalent to typing Ctrl/Y followed by the DCL command 
DEBUG at that point. 

You can pass commands to the debugger at the time you signal it with SS$_ 
DEBUG. The commands you want the debugger to execute should be specified 
as you would enter them at the DBG> prompt. Multiple commands should be 
separated by semicolons. The commands should be passed by reference as an 
ASCIC string. See your language documentation for details on constructing an 
ASCIC string. 

For example, to invoke the debugger and enter a SHOW CALLS command at a 
given point in your program, you could insert the following code in your program 
(BLISS example): 

LIB$SIGNAL(SS$_DEBUG, 1, UPLIT BYTE(%ASCIC 'SHOW CALLS')); 

You can obtain the definition of SS$_DEBUG at compile time from 
the appropriate STARLET or SYSDEF file for your language (for 
example STARLET.L32 for BLISS or FORSYSDEF.TLB for FORTRAN). 

You can also obtain the definition of SS$_JDEBUG at link time in 
SYS$LIBRARY:STARLET.OLB (this method is less desirable). 

D.2 Logical Names 

The following list identifies debugger-specific logical names. 

Logical 

Name Description 

DBG$INIT Specifies your debugger initialization file. Default: no 

debugger initialization file. DBG$INIT accepts a full or 
partial VMS file specification as well as a search list. See 
Section 8.2 for information about debugger initialization files. 

DBG$INPUT Specifies the debugger input device. Default: SYS$INPUT. 

See Section 9.2 for information about using DBG$INPUT and 
DBG$OUTPUT to debug screen-oriented programs at two 
terminals. 

DBG$INPUT is ignored in the DECwindows interface (see 
DBG$DECW$DISPLAY). You can use DBG$INPUT if you are 
displaying the debugger’s command interface in a DECterm 
window (see Section 1.6.3.3). 
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D.2 Logical Names 


Logical 

Name 

Description 

DBG$OUTPUT 

Specifies the debugger output device. Default: 

SYS$OUTPUT. See Section 9.2 for information about using 
DBG$INPUT and DBG$OUTPUT to debug screen-oriented 
programs at two terminals. 

DBG$OUTPUT is ignored in the DECwindows interface 
(see DBG$DECW$DISPLAY). You can use DBG$OUTPUT 
if you are displaying the debugger’s command interface in a 
DECterm window (see Section 1.6.3.3). 

DBG$PROCESS 

Specifies the debugging configuration (default or 
multiprocess). Default: DBG$PROCESS is undefined. See 
Section 10.2.1 for information about using DBG$PROCESS 
to specify the debugging configuration. 

DBG$DECW$DISPLAY 

Applies only to workstations running DECwindows. Specifies 
the debugger interface (DECwindows or command) or the 
display device. Default: DBG$DECW$DISPLAY is either 
undefined or has the same definition as the application¬ 
wide logical name DECW$DISPLAY. See Section 1.6.3 
for information about using DBG$DECW$DISPLAY to 
override the debugger’s default interface in the DECwindows 
environment. 


Use the DCL command DEFINE or ASSIGN to assign values to these logical 
names. For example, the following command specifies the location of the debugger 
initialization file: 

$ DEFINE DBG$INIT DISK$:[JONES.COMFILES]DEBUGINIT.COM 

Note the following points about the logical name DBG$INPUT. If you plan to 
debug a program that takes its input from a file (for example, PROG_IN.DAT) 
and your debugger input from the terminal, establish the following definitions 
before invoking the debugger: 

$ DEFINE SYS$INPUT PROG_IN.DAT 

$ DEFINE/PROCESS DBG$INPUT 'F$LOGICAL("SYS$COMMAND") 

That is, define DBG$INPUT to point to the translation of SYS$COMMAND. If 
you define DBG$INPUT to point to SYS$COMMAND, the debugger tries to get 
its input from the file, PROG_IN.DAT. 

D.3 Built-In Symbols 

The debugger’s built-in symbols provide options for specifying program entities 
and values. 

Most of the debugger built-in symbols have a percent sign (%) prefix. 

The following symbols are described in this appendix: 

• %R0 to %R11, %AP, %FP, %SP, %PC, %PSL—Used to specify the VAX general 
registers. 

• %V0 to %V15, %VCR, %VLR, and %VMR—Used to specify the VAX vector 
registers and vector control registers. 

• %NAME—Used to construct identifiers. 

• %PARCNT—Used in command procedures to count parameters passed. 
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D.3 Built-In Symbols 


• %DECWINDOWS—Used in debugger command procedures or initialization 
files to determine whether the debugger’s command interface or DECwindows 
interface was invoked. 

• %BIN, %DEC, %HEX, %OCT—Used to control the input radix. 

• Period (.), Return key, circumflex ( A ), backslash (\ ), %CURLOC, 
%NEXTLOC, %PREVLOC, %CURVAL—Used to specify consecutive program 
locations and the current value of an entity. 

• Plus sign ( + ), minus sign (-), multiplication sign (*), division sign (/), at 
sign (@), period (.), bit field operator (<p,s,e>), %LABEL, %LINE, backslash 
(\ ) —Used as operators in address expressions. 

• %ADAEXC_NAME, %EXC_FACILITY, %EXC_NAME, %EXC_NUMBER, 
%EXC_SEVERITY—Used to obtain information about exceptions. 

• %CURRENT_SCOPE_ENTRY, %NEXT_SCOPE_ENTRY, %PREVIOUS_ 
SCOPE_ENTRY—Used to specify the current, next, and previous scope 
relative to the call stack. 

The following symbols are described elsewhere in this manual, as indicated: 

• %ADDR, %DESCR, %REF, %VAL—Used to specify the argument passing 
mechanism for the CALL command. See the CALL command description in 
the command dictionary. 

• %PROCESS_NAME, %PROCESS_PID, %PROCESS_NUMBER, %NEXT_ 
PROCESS, %PREVIOUS_PROCESS, %VISIBLE_PROCESS—Used to specify 
processes in multiprocess programs. See Section 10.2.2. 

• %ACTIVE_TASK, %CALLER_TASK, %NEXT_TASK, %PREVIOUS_TASK, 
%TASK, %VISIBLE_TASK—Used to specify tasks or threads in tasking or 
multithread programs. See Section 12.3.4. 

• %PAGE, %WIDTH—Used to specify the current screen height and width. See 
Section C.4.1. 

• %SOURCE_SCOPE, %INST_SCOPE—Used to specify the scope for source 
and instruction display in screen mode. See Section C.3.1 and Section C.3.4, 
respectively. 

• %CURDISP, %CURSCROLL, %NEXTDISP, %NEXTINST, %NEXTOUTPUT 
%NEXTSCROLL, %NEXTSOURCE—Used in screen mode to specify displays 
in the display list. See Section C.4.2. 

D.3.1 Specifying the VAX Registers 

The debugger built-in symbol for a VAX register is the register name preceded 
by the percent sign (%). When specifying a register symbol, you can omit the 

percent sign (%) prefix if your program has not declared a symbol with the same 
name. 
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The register symbols are identified in the following list. 


Symbol Description 


VAX General Registers 


%R0 ... %R11 

General purpose registers (RO . . . Rll) 

%AP (%R12) 

Argument pointer (AP) 

%FP (%R13) 

Frame pointer (FP) 

%SP (%R14) 

Stack pointer (SP) 

%PC (%R15) 

Program counter (PC) 

%PSL 

Processor status longword (PSL) 

VAX Vector Registers and Vector Control Registers 

%V0 . . . %V15 

Vector registers VO ... VI5 

%VCR 

Vector count register 

%VLR 

Vector length register 

%VMR 

Vector mask register 


See Section 4.4 and Section 4.3.1 for more information about the general registers. 
See Chapter 11 for more information about the vector registers. 


D.3.2 Constructing Identifiers 

The %NAME built-in symbol enables you to construct identifiers that are not 
ordinarily legal in the current language. The syntax is as follows: 

%NAME ’ character-string' 

In the following example, the variable with the name 12’ is examined: 

dbg> EXAMINE %NAME '12' 

In the following example, the compiler-generated label P.AAA is examined: 

DBG> EXAMINE %NAME 'P.AAA' 

D.3.3 Counting Parameters Passed to Command Procedures 

The %PARCNT built-in symbol can be used within a command procedure that 
accepts a variable number of actual parameters (%PARCNT is defined only within 
a debugger command procedure). 

%PAB.CNT specifies the number of actual parameters passed to the current 
command procedure. In the following example, command procedure ABC.COM is 
invoked and three parameters are passed: 

DBG> @ABC 111,222,333 

Within ABC.COM, %PAKCNT now has the value 3. %PARCNT is then used as a 
loop counter to obtain the value of each parameter passed to ABC.COM: 

DBG> FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X) 
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D.3.4 Determining the Debugger Interface (Command or DECwindows) 

The %DECWINDOWS built-in symbol enables you to determine whether 
the debugger’s DECwindows or command interface was invoked. When the 
DECwindows interface is being used, the value of %DECWINDOWS is 1 (TRUE). 
When the command interface is being used, the value of %DECWINDOWS is 0 
(FALSE). For example: 

DBG> EVALUATE %DECWINDOWS 
0 

The following example shows how to use %DECWINDOWS in a debugger 
initialization file to position the debugger source window, SRC, at debugger 
startup: 

IF IDECWINDOWS THEN 

! DECwindows (workstation) syntax: 

(DISPLAY SRC AT (100,300,100,700)) 

ELSE 

! Screen-mode (terminal) syntax: 

(DISPLAY SRC AT (AT HI)) 

D.3.5 Controlling the Input Radix 

The built-in symbols %BIN, %DEC, %HEX, and %OCT can be used in address 
expressions and language expressions to specify that an integer literal that 
follows (or all integer literals in a parenthesized expression that follows) should 
be interpreted in binary, decimal, hexadecimal, or octal radix, respectively. Use 
these radix built-in symbols only with integer literals. 

For example: 

DBG> EVALUATE/DEC %HEX 10 
16 

DBG> EVALUATE/DEC %HEX (10 + 10) 

32 

DBG> EVALUATE/DEC %BIN 10 
2 

DBG> EVALUATE/DEC %OCT (10 + 10) 

16 

DBG> EVALUATE/HEX %DEC 10 
0A 

DBG> SET RADIX DECIMAL 

DBG> EVALUATE %HEX 20+33 ! Treat 20 as hexadecimal, 33 as decimal 
65 ! Resulting value is decimal 

DBG> EVALUATE %HEX (20+33) ! Treat both 20 and 33 as hexadecimal 
83 

DBG> EVALUATE %HEX (20+ %OCT 10 +33) ! Treat 20 and 33 as 

! hexadecimal and 10 as octal 

DBG> SYMBOLIZE IHEX 27C9E3 ! Symbolize a hexadecimal address 

DBG> DEPOSIT/INST %HEX 5432 = 'MOVL A 0%DEC 222, Rl' 

DBG> ! Treat address 5432 as hexadecimal, and operand 222 as decimal 

D.3.6 Specifying Program Locations and the Current Value of an Entity 

The following built-in symbols enable you to specify program locations and the 
current value of an entity. 
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Symbol 

%CURLOC 
. (period) 

%NEXTLOC 
Return key 


%PREVLOC 
A (circumflex) 

%CURVAL 
\ (backslash) 


Description 

Current logical entity—the program location last referenced by an 

EXAMINE, DEPOSIT, or EVALUATE/ADDRESS command. 


Logical successor of the current entity—the program location that 
logically follows the location last referenced by an EXAMINE, 
DEPOSIT, or EVALUATE/ADDRESS command. Because the 
Return key is a command terminator, it can be used only where a 
command terminator is appropriate (for example, immediately after 
EXAMINE, but not immediately after DEPOSIT or EVALUATE 


/ADDRESS). 

Logical predecessor of current entity—the program location that 
logically precedes the location last referenced by an EXAMINE, 
DEPOSIT, or EVALUATE/ADDRESS command. 


Value last displayed by an EVALUATE or EXAMINE command, 
or deposited by a DEPOSIT command. These two symbols are not 
affected by an EVALUATE/ADDRESS command.__ 


In the following example, the variable WIDTH is examined; the value 12 is then 
deposited into the current location (WIDTH); this is verified by examining the 
current location: 


DBG> EXAMINE WIDTH 
MODVWIDTH: 7 
DBG> DEPOSIT . = 12 
DBG> EXAMINE . 

MOD\WIDTH: 12 
DBG> EXAMINE ICURLOC 
MOD\WIDTH: 12 
DBG> 

In the next example, the next and previous locations in an array are examined: 

DBG> EXAMINE PRIMES(4) 

MOD\PRIMES(4): 7 
DBG> EXAMINE %NEXTLOC 
MOD\PRIMES(5): 11 

DBG> EXAMINE l Return | ! Examine next location 

MOD\PRIMES(6): 13 

DBG> EXAMINE IPREVLOC 

MOD\PRIMES(5): 11 

DBG> EXAMINE A 

MOD\PRIMES(4): 7 

DBG> 

Note that using the Return key to signify the logical successor does not apply 
to all contexts. For example, you cannot press the Return key after typing the 
command DEPOSIT to indicate the next location, whereas you can always use the 
symbol %NEXTLOC for that purpose. 

D.3.7 Using Symbols and Operators in Address Expressions 

The symbols and operators that can be used in address expressions are listed 
below. A unary operator has one operand. A binary operator has two operands. 
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Symbol 

Description 

%LABEL 

Specifies that the numeric literal that follows is a program 
label (for languages like FORTRAN that have numeric 
program labels). You can qualify the label with a path 
name prefix that specifies the containing module. 

%LINE 

Specifies that the numeric literal that follows is a line 
number in your program. You can qualify the line number 
with a path name prefix that specifies the containing 
module. 

Backslash (\ ) 

When used within a path name, delimits each element of 
the path name. In this context, the backslash cannot be 
the leftmost element of the complete path name. 

When used as the prefix to a symbol, specifies that the 
symbol is to be interpreted as a global symbol. In this 
context, the backslash must be the leftmost element of the 
symbors complete path name. 

At sign (@) 

Period (.) 

Unary operators. In an address expression, the at sign 
(@) and period (.) each function as a "contents-of" 
operator. The "contents-of" operator causes its operand 
to be interpreted as a memory address and thus requests 
the contents of (or value residing at) that address. 

Bit field <p,s,e> 

Unary operator. You can apply bit field selection to an 
address-expression. To select a bit field, you supply a bit 
offset (p), a bit length (s), and a sign extension bit (e), 
which is optional. 

Plus sign (+) 

Unary or binary operator. As a unary operator, indicates 
the unchanged value of its operand. As a binary operator, 
adds the preceding operand and succeeding operand 
together. 

Minus sign (-) 

Unary or binary operator. As a unary operator, indicates 
the negation of the value of its operand. As a binary 
operator, subtracts the succeeding operand from the 
preceding operand. 

Multiplication sign (*) 

Binary operator. Multiplies the preceding operand by the 
succeeding operand. 

Division sign (/) 

Binary operator. Divides the preceding operand by the 
succeeding operand. 


The following examples illustrate the use of built-in symbols and operators in 
address expressions. 

%LINE and %LABEL Operators 

The following command sets a tracepoint at line 26 of the module in which 
execution is currently suspended: 

DBG> SET TRACE %LINE 26 

The next command displays the source line associated with line 47: 

DBG> EXAMINE/SOURCE %LINE 47 
module MAIN 

47: procedure SWAP(X,Y: in out INTEGER) is 

DBG> 

The next command sets a breakpoint at label 10 of module MOD4: 

DBG> SET BREAK M0D4\!LABEL 10 
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Path Name Operators 

The following command displays the value of the variable COUNT that is 
declared in routine ROUT2 of module MOD4. The backslash (\ ) path name 
delimiter separates the path name elements: 

DBG> EXAMINE MOD4\ROUT2\COUNT 

MOD 4\R0UT2\COUNT: 12 

DBG> 

The following command sets a breakpoint on line 26 of the module QUEUMAN: 

DBG> SET BREAK QUEUMANULINE 26 

The following command displays the value of the global symbol X: 

DBG> EXAMINE \X 

Arithmetic Operators 

The order in which the debugger evaluates the elements of an address expression 
is similar to that used by most programming languages. The order is determined 
by the following three factors, listed in decreasing order of precedence (first listed 
have higher precedence): 

1. The use of delimiters (usually parentheses or brackets) to group operands 
with particular operators 

2. The assignment of relative priority to each operator 

3. Left-to-right priority of operators 

The debugger operators are listed in decreasing order of precedence as follows: 

1. Unary operators ((.),(@),( + ),(—)) 

2. Multiplication and division operators ((*),(/)) 

3. Addition and subtraction operators (( + ),(-)) 

For example, when evaluating the following expression, the debugger first adds 
the operands within parentheses, then divides the result by 4, then subtracts the 

result from 5. 

5-(T+5)/4 

The following command displays the value contained in the memory location X + 

4 bytes: 

DBG> EXAMINE X + 4 

Contents-of Operator 

The following examples illustrate use of the contents-of operator. In the next 
example, the instruction at the current PC value is obtained (the instruction 
whose address is contained in the PC and which is about to execute): 

DBG> EXAMINE .%PC 
MOD\%LINE 5: PUSHL S A #8 
DBG> 

In the next example, the source line at the PC value one level down the call stack 
is obtained (at the call to routine SWAP): 

DBG> EXAMINE/SOURCE .1\%PC 
module MAIN 

MAIN\%LINE 134: SWAP(X,Y); 

DBG> 
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D.3.8 


For the next example, assume that the value of pointer variable PTR is 7FF00000 
hexadecimal, the address of an entity that you want to examine. Assume further 
that the value of this entity is 3FF00000 hexadecimal. The following command 
shows how to examine the entity: 

DBG> EXAMINE/LONG .PTR 
7FF00000: 3FF00000 
DBG> 

In the next example, the contents-of operator (at sign or period) is used with the 
current location operator (period) to examine a linked list of three quadword- 
integer pointer variables (identified as LI, L2, and L3 in the illustration that 
follows). P is a pointer to the start of the list. The low longword of each pointer 
variable contains the address of the next variable; the high longword of each 
variable contains its integer value (8, 6, and 12, respectively). 


P: 


9B40 


LI 

L2 

L3 

9BDA 


9BF4 


0000 



8 


6 


12 


ZK-7936-GE 


DBG> SET TYPE QUADWORD; SET 
DBG> EXAMINE .P 

00009BC2: 00000008 00009BDA 

DBG> EXAMINE @. 

00009BDA: 00000006 00009BF4 

DBG> EXAMINE .. 

00009BF4: 0000000C 00000000 


RADIX HEX 

! Examine the entity whose address 
! is contained in P. 

! High word has value 8, low word 
! has address of next entity (9BDA). 

! Examine the entity whose address 
! is contained in the current entity. 

! High word has value 6, low word 
! has address of next entity (9BF4). 

! Examine the entity whose address 
! is contained in the current entity. 

! High word has value 12 (dec.), low word 
! has address 0 (end of list). 


Bit-Field Operator 


The following example shows how to use the bit-field operator. For example to 
examine the address expression X_NAME starting at bit 3 with a length of 4 bits 
and no sign extension, you would enter the following command: 

DBG> EXAMINE X_NAME <3,4,0> 


Obtaining Information About Exceptions 

The following built-in symbols enable you to obtain information about the current 
exception and use that information to qualify breakpoints or tracepoints. 






Symbol 

%EXC FACILITY 

%EXC_NAME 


Description 

Name of facility that issued the current exception 

Name of current exception 
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Symbol 

Description 

%ADAEXC_NAME 

%EXC_NUMBER 

%exc severity 

Ada exception name of current exception (for Ada programs only) 

Number of current exception 

Severity code of current exception 

For example: 


dbg> evaluate %exc_name 

"FLTDIV F” 

DBG> SET BREAK/EXCEPTION WHEN (%EXC_NAME = "FLTDIV_F") 


DBG> EVALUATE %EXC_NUMBER 
12 

DBG> EVALUATE/CONDITION_VALUE %EXC_NUMBER _ 

%SYSTEM-F-ACCVIO, access violation at PC !XL, virtual address .XL 
DBG> SET BREAK/EXCEPTION WHEN (%EXC_NUMBER = 12) 

Note that the conditional expressions in the WHEN clauses are language-specific. 

D.3.9 Specifying the Current, Next, and Previous Scope on the Call Stack 

You can use the following built-in symbols to obtain and manipulate the scope for 
symbol lookup and for source or instruction display relative to the routine call 

stack. 


Built-in Symbol 


Description 


%CURRENT_SCOPE_ENTRY 

%NEXT_SCOPE_ENTRY 

%PREVIOUS_SCOPE_ENTRY 


The call frame that the debugger is currently using 

as reference when displaying source code or decoded 
VAX instructions, or when searching for symbols. By 
default, this is call frame 0. 

The next call frame down the call stack from the call 
frame denoted by %CURRENT_SCOPE_ENTRY. 

The next call frame up the call stack from the call 
frame denoted by %CURRENT SCOPE ENTRY. 


These symbols return integer values that denote a call frame on the call stack. 
Call frame 0 denotes the routine at the top of the stack, where execution is 
suspended. Call frame 1 denotes the calling routine, and so on. 

For example, the following command specifies that the debugger search for 
symbols starting with the scope denoted by the next routine down the call stack 
(rather than starting with the routine at the top of the call stack). 

DBG> SET SCOPE/CURRENT %NEXT_SC0PE_ENTRY 
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Summary of Debugger Support for Languages 


You can use the debugger with the following VAX languages: 

Ada 

BASIC 

BLISS 

C 

COBOL 

DIBOL 

FORTRAN 

MACRO-32 

Pascal 

PL/I 

RPGII 

SCAN 

The debugger recognizes the syntax, data typing, and scoping rules of each 
language. It also recognizes each language’s operators and expression syntax. 
Therefore, when using debugger commands you can specify variables and other 
program entities as you might in the source code of the program. And you can 
compute the value of a source-language expression using the syntax of that 
language. 

Other parts of this manual describe debugging techniques that are common to 
most of the supported languages. This appendix provides additional information 
that is specific to each language: 

• Supported operators in language expressions 

Supported constructs in language expressions and address expressions 

• Supported data types 

• Any other language-specific information, including restrictions in debugger 
support, if any 

For more information about language-specific debugger support, refer to the 
documentation furnished with a particular language. 

If your program is written in more than one language, you can change the 
debugging context from one language to another during a debugging session. 

To do so, use the SET LANGUAGE command, specifying one of the following 
keywords: 

ADA 

BASIC 

BLISS 

C 

COBOL 

DIBOL 
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FORTRAN 

MACRO-32 

PASCAL 

PL/I 

RPGII 

SCAN 

UNKOWN 

When debugging a program that is written in an unsupported language, enter 
the SET LANGUAGE UNKNOWN command. To maximize the usability of the 
debugger with unsupported languages, this setting causes the debugger to accept 
a large set of data formats and operators, including some that might be specific 
to only a few supported languages. For information about the operators and 
constructs that are recognized when the language is set to UNKNOWN, see 
Section E.13. 

E.1 Ada 

T his section describes debugger support for Ada. For information specific to Ada 
tasking programs, see also Chapter 12. 

E.1.1 Ada Names and Symbols 

The following sections present the debugger support for Ada names and symbols, 
including predefined attributes. 

Note that parts of names may be language expressions—for example, attributes 
such as ’FIRST or ’POS. This affects how you use the EXAMINE, EVALUATE, 
and DEPOSIT commands with such names. See the examples of enumeration 
types in Section E.l. 1.2.1. 

E.1.1.1 Ada Names 

Supported Ada names follow: 


Kind of Name 

Lexical elements 


Indexed components 
Slices 


Selected components 


Debugge r Support ___ 

Full support for Ada rules for the syntax of identifiers. 

Function designators that are operator symbols (for example, 
+ and *) rather than identifiers must be prefixed with 
%NAME. Also, the operator symbol must be enclosed in 
quotation marks. 

Full support for Ada rules for numeric literals, character 
literals, string literals, and reserved words. 

The debugger accepts signed integer literals in the range 
-2147483648 to 2147483647. 

Depending on context, the debugger interprets floating-point 
types as F_floating, D_floating, G_floating, or H_floating. 

Full support. 

You can examine and evaluate an entire slice or an indexed 
component of a slice. 

You can deposit only to an indexed component of a slice. You 
cannot deposit an entire slice. 

Full support, including use of the keyword all in .all. 
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Kind of Name 

Debugger Support 

Literals 

Full support, including the keyword null. 

Boolean symbols 

Full support (TRUE, FALSE) 

Aggregates 

You can examine the entire record and array objects with 
the EXAMINE command. You can deposit a value in a 
component of an array or record. You cannot use the 
DEPOSIT command with aggregates, except to deposit 
character string values. 

E.1.1.2 Predefined Attributes 

Supported Ada predefined attributes follow. Note that the debugger SHOW 

SYMBuL/I'YFE command provides the same information that is provided bv the 

P'FIRST, P' LAST, P'LENGTH, P'SIZE, and P'CONSTRAINED attributes 

Attribute 

Debugger Support 

P' CONSTRAINED 

For a prefix P that denotes a record object with discriminants. 

The value of P' CONSTRAINED reflects the current state of P 
(constrained or unconstrained). 

P' FIRST 

For a prefix P that denotes an enumeration type or a subtype of 
an enumeration type. Yields the lower bound of P. 

P' FIRST 

For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the lower bound of 
the first index range. 

P' FIRST(N) 

For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the lower bound of 
the Nth index range. 

P' LAST 

For a prefix P that denotes an enumeration type, or a subtype of 
an enumeration type. Yields the upper bound of P. 

P' LAST 

For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the upper bound of 
the first index range. 

P' LAST(N) 

For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the upper bound of 
the Nth index range. 

P' LENGTH 

For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the number of values 
of the first index range (zero for a null range). 

P' LENGTH(N) 

For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the number of values 
of the Nth index range (zero for a null range). 

P' POS(X) 

For a prefix P that denotes an enumeration type or a subtype of 
an enumeration type. Yields the position number of the value X 

The first position is 0. 

P' PRED(X) 

For a prefix P that denotes an enumeration type or a subtype 
of an enumeration type. Yields the value of type P which has a 
position number one less than that of X. 
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Attribute 

Debugger Support 

P' SIZE 

For a prefix P that denotes an object. Yields the number of bits 
allocated to hold the object. 

P' SUCC(X) 

For a prefix P that denotes an enumeration type or a subtype 
of an enumeration type. Yields the value of type P which has a 


position number one more than that of X. 

P'VAL(N) 

For a prefix P that denotes an enumeration type or a subtype of 
an enumeration type. Yields the value of type P which has the 


position number N. The first position is 0. 


E.l.1.2.1 Specifying Attributes with Enumeration Types Consider the following 
declarations: 


type DAY is 

(MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY, SATURDAY,SUNDAY); 

MY_DAY : DAY; 

The following examples show the use of attributes with enumeration types. 

Note that you cannot use the EXAMINE command to determine the value 
of attributes, because attributes are not variable names. You must use the 
EVALUATE command instead. For the same reason, attributes can appear only 
on the right of the := operator in a DEPOSIT command. 

DBG> EVALUATE DAY'FIRST 
MONDAY 

DBG> EVALUATE DAY' POS(WEDNESDAY) 

2 

DBG> EVALUATE DAY'VAL(4) 

FRIDAY 

DBG> DEPOSIT MY_DAY := TUESDAY 
DBG> EVALUATE DAY'SUCC(MY_DAY) 

WEDNESDAY 

DBG> DEPOSIT . := DAY'PRED(MY_DAY) 

DBG> EXAMINE . 

EXAMPLE.MY_DAY: MONDAY 

DBG> EVALUATE DAY'PRED(MY_DAY) 

%DEBUG-W-ILLENUMVAL, enumeration value out of legal range 

E.l .1.2.2 Resolving Overloaded Enumeration Literals Consider the following 
declarations: 

type MASK is (DEC,FIX,EXP); 
type CODE is (FIX,CLA,DEC); 

MY_MASK : MASK; 

MY_CODE : CODE; 

In the following example, the qualified expression CODE'(FIX) resolves the 
overloaded enumeration literal FIX, which belongs to both type CODE and type 
MASK: 

DBG> DEPOSIT MY_CODE := FIX 
%DEBUG-W-NOUNIQUE, symbol 'FIX' is not unique 
DBG> SHOW SYMBOL/TYPE FIX 

data EXAMPLE.FIX . , u 

enumeration type (CODE, 3 elements), size: 1 byte 

data EXAMPLE.FIX , 

enumeration type (MASK, 3 elements), size: 1 byte 
DBG> DEPOSIT MY_C0DE := CODE'(FIX) 

DBG> EXAMINE MY_CODE 
EXAMPLE.MY CODE: FIX 


E-4 









Summary of Debugger Support for Languages 

E.1 Ada 


E.1.2 Operators and Expressions 

The following sections present the debugger support for Ada operators and 
language expressions. 

E.1.2.1 Operators in Language Expressions 

Supported Ada operators in language expressions follow: 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus (identity) 

Prefix 

~ 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 


Multiplication 

Infix 

/ 

Division 

Infix 

MOD 

Modulus 

Infix 

REM 

Remainder 

Infix 


Exponentiation 

Prefix 

ABS 

Absolute value 

Infix 

& 

Concatenation (only string types) 

Infix 

= 

Equality (only scalar and string types) 

Infix 

/= 

Inequality (only scalar and string types) 

Infix 

> 

Greater than (only scalar and string types) 

Infix 

>= 

Greater than or equal (only scalar and string types) 

Infix 

< 

Less than (only scalar and string types) 

Infix 

<= 

Less than or equal (only scalar and string types) 

Prefix 

NOT 

Logical NOT 

Infix 

AND 

Logical AND (not for bit arrays) 

Infix 

OR 

Logical OR (not for bit arrays) 

Infix 

XOR 

Logical exclusive OR (not for bit arrays) 


The debugger does not support the following items: 

• Operations on entire arrays or records 

• The short-circuit control forms: and then, or else 

• The membership tests: in, not in 

• User-defined operators 
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E.1.2.2 Language Expressions 

Supported Ada expressions follow: 


Kind of Expressio n Debugger Support ___ 

Type conversions -No support for any of the explicit type conversions specified 

in Ada. However, the debugger performs certain implicit type 
conversions between numeric types during the evaluation of 
expressions. 

The debugger converts lower-precision types to higher-precision 
types before evaluating expressions involving types of different 
precision: 

• If integer and floating-point types are mixed, the integer 
type is converted to floating-point type. 

• If integer and fixed-point types are mixed, the integer type 
is converted to fixed-point type. 

• If integer types of different sizes are mixed (for example, 
byte-integer and word-integer), the one with the smaller 
size is converted to the larger size. 

Full support. Note that the debugger denotes subtypes and 
types that have range constraints as "subrange” types. 

Supported as required to resolve overloaded enumeration 
literals (literals that have the same identifier but belong to 
different enumeration types). The debugger does not support 
qualified expressions for any other purpose. 

No support for any operations with allocators. 

Universal expressions No support. 

E.1.3 Data Types 

Supported Ada data types follow: 

Ada Data Type VAX Data Type Name 

INTEGER 
SHORTJNTEGER 
SHORT_SHORT_INTEGER 
SYSTEM.UNSIGNED_QUADWORD 
SYSTEM.UNSIGNED__LON GW ORD 
SYSTEM.UNSIGNEDJWORD 
SYSTEM.UNSIGNEDJBYTE 
FLOAT 

SYSTEM.F_FLOAT 
SYSTEM.D_FLOAT 
LONG_FLOAT 


SYSTEM.G_FLOAT 


Longword Integer (L) 

Word Integer (W) 

Byte Integer (B) 

Quadword Unsigned (QU) 

Longword Unsigned (LU) 

Word Unsigned (WU) 

Byte Unsigned (BU) 

F_Floating (F) 

F_Floating(F) 

D_Floating (D) 

DJFloating (D), if pragma LONG_FLOAT 
(D_FLOAT) is in effect. G_Floating (G), 
if pragma LONG_FLOAT (G_FLOAT) is in 
effect. 

G_Floating (G) 


Subtypes 

Qualified expressions 

Allocators 
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Ada Data Type 

VAX Data Type Name 

SYSTEM.H FLOAT 

H_Floating (H) 

LONG_LONG_FLOAT 

H_Floating (H) 

Fixed 

(None) 

STRING 

ASCII Text ( T ) 

BOOLEAN 

Aligned Bit String (V) 

BOOLEAN 

Unaligned Bit String (VU) 

Enumeration 

For any enumeration type whose value fits 
into an unsigned byte or word: Byte Unsigned 
(BU) or Word Unsigned (WU), respectively. 
Otherwise: No corresponding VAX data type. 

Arrays 

(None) 

Records 

(None) 

Access (pointers) 

(None) 

Tasks 

(None) 


E.1.4 Compiling and Linking 

The Ada predefined units in the ADA$PREDEFINED program library on your 
system have been compiled with the /NODEBUG qualifier. Before using the 
debugger to refer to names declared in the predefined units, you must first copy 
the predefined unit source files using the ACS EXTRACT SOURCE command 
then you must compile the copies into the appropriate library with the /DEBUG 
qualifier, and relink the program with the /DEBUG qualifier. 

onWloh !^ 6 T^ DEBU . G quaHfi f with one of'the Ada compilation commands, 
y g al symbol records are included in the modules for debugging. Global 

symbols in this case are names that the program exports to modules in other 
languages by means of the Ada export pragmas: EXPORT PROPFDTTPF 

EXPORTJEXCEPTION, and PSECT_OBJECT. 

The /DEBUG qualifier on the ACS LINK command causes the linker to include 
image ^ mformati ° n in the closure of the specified unit in the executable 


E.1.5 Source Display 


Source code may not be available for display for the following reasons that are 
specific to Ada programs: 

Execution is suspended within Ada initialization or elaboration code for 
which no source code is available. 

The copied source file is not in the program library where the unit was 
originally compiled. 

complied ™ 31 S ° UrC6 file is not where it; was when the unit was originally 

The source file has been modified since the executable image was generated, 
and the original copied source file or external source file no longer exists. 

The following paragraphs explain how to control the display of source code with 
Ada programs. 


E-7 







Summary of Debugger Support for Languages 
E.1 Ada 


If the compiler command’s /COPY.SOURCE qualifier (the default) was in effect 
when you compiled your program, the debugger obtains the displayed Ada 
source code from the copied source files located in the program library where 
the program was originally compiled. If you compiled your program with the 
/NOCOPY SOURCE qualifier, the debugger obtains the displayed Ada source 
code from the external source files associated with your program s compilation 

units. 

The file specifications of the copied or external source files*ire in 

the associated object files. For example, if you have used the ACS COPY UNIT 
command to copy units, or the DCL COPY or BACKUP command to copy an 
entire library, the debugger still searches the original program hbraiy for copied 
source files. If, after copying, the original units have been modified or the original 
library has been deleted, the debugger may not find the original C 0 P ieds ™ rce 
files. Similarly, if you have moved the external source files to another disk or 
directory, the debugger may not find them. 

In such cases, use the SET SOURCE command to locate the correct files for 
source display. You can specify a search list of one or more program libraiy or 
source code directories. For example (ADA$LIB is the logical name that the 
program library manager equates to the current program library). 

DBG> SET SOURCE ADA$LIB,DISK:[SMITH.SHARE.ADALIB] 

The SET SOURCE command does not affect the search list for the external source 
files that the debugger fetches when you use the debugger EDIT com™^ d ^ 
tell the EDIT command where to look for your source files, use the SET SOURCE 

/EDIT command. 

E.1.6 EDIT Command 

With Ada programs, by default the debugger EDIT command fetches the external 
source filetiiat was compiled to produce the compilation unit in which execution 
is currently suspended. You do not edit the copied source file, in the program 
library, that the debugger uses for source display. 

The file specifications of the source files you edit are embedded in the associated 
object files during compilation (unless you specify /NODEBUG), f some s^rce 
files have been relocated after compilation, the debugger may not find them. 

In such cases you can use the debugger SET SOURCE/EDIT command to specify 
a search list of one or more directories where the debugger should look for source 

files. For example: 

DBG> SET SOURCE/EDIT [],USER:[JONES.PROJ.SOURCES] 

The SET SOURCE/EDIT command does not affect the search list for copied 
source files that the debugger uses for source display. 

The SHOW SOURCE/EDIT command displays the source-file search list currently 
being used for the EDIT command. The CANCEL SOURCE/EDIT command 
cancels the source-file search list currently being used for the EDIT command an 
restores the default search mode. 
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E.1.7 GO and STEP Commands 

p“s f0ll0Wlng POintS ab0Ut USing the 00 and STEP commands with Ada 

OTEP lml a t debUg ? n ? session use the GO command rather than the 
coda d t0 aVOld steppmg trough compiler-generated initialization 

~ S 8 ® i he 00 c0mmand t0 SO directly to the preset breakpoint at the start 
ot the mam program, past the initialization and package elaboration code. 

~ 2“.*®, G h ° C ° mmaadand breakpoints to suspend execution at the start 
Dro^rpm b ° ratl0n ° f llbrary P acka ges, before execution reaches the main 

prUgTclIIl. 

Section E.1.8 explains how to monitor the package elaboration phase. 

staJ^?^ ?r re than ° ne Statement > a STEP command executes all the 
statements on that line as part of a single step. 

Xtn entiy CaUS ! re j 0t the Same as subpr °gr a m calls because task 
^ , Sare queued aad may not execute right away. If you use the STEP 

X^you expecT 6 ^ ** & Cal1 ’ the results mi ght not be 

E.1.8 Debugging Ada Library Packages 

When an Ada main program (or a non-Ada main program that calls Ada 
code) is executed, initialization code is executed for the Ada run-time library 
a ,^ delab0ratl0 , n code for a11 hbrary units that the program depends on. ThI 

before thT m C ° de CaUS6S the hbrary UldtS t0 be elaborated ^ appropriate order 
thXnh t Pr °f ia executed - Library specifications, bodies, and some of 
their subunits are also elaborated by this process. 

The elaboration of library packages accomplishes the following operations: 

• Causes package declarations to take effect 

Initializes any variables whose declaration includes initialization code 

' l i^mt3paXg?b^ tementS ‘ hat ^ betWe “ ^ begi ” a " d «" d 

kdtSlv°hpfn V °^ the . debug f r with an Ada program, execution is suspended 

Ubra^uSL P^exlplr “ eiieCUted and before ““ ekbOTa ‘ i °” 

$ RUN FORMS 

VAX DEBUG Version 5.5 

IDEBUG-I-INITIAL, language is ADA, module set to FORMS 
SDEBUG-I-NOTATMAIN, type GO to ge^ to start If LL^rogram 

At that point, before typing GO to get to the start of the main program, you can 
step through and examine parts of the library packages by setting breakpoints at 
e package specifications or bodies you are interested in. You then use the GO 

XvX f° ?? t0 Start ° f each package - To set a breakpoint a package 
body specify the package unit name with the SET BREAK command To set a 

specify the "* ■— 
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Even if you have set a breakpoint on a package body, the break will not occur if 
the debugger module for that body is not set. If the module is not set, the break 
will occur at the package specification. This effect occurs because e eugger 
automatically sets modules for the specifications of packages named in with 
clauses; it does not automatically set modules for the associated package bodies 
(see Section E.1.14). 

Also, to set a breakpoint on a subprogram declared in a package specification, you 
must set the module for the package body. 

Note that the compiler generates unique names for ^P^Xttul^these 
library packages that are or could be overloaded names. The debugger uses these 

unique names in its output, and requires them in commands where the na 
would otherwise be ambiguous. For more information on resolving overloaded 
names and symbols, see Section E.1.15. 

E.1.9 Predefined Breakpoints 

When you invoke the debugger with an Ada program (or a n on-Ada program 
that calls Ada code), two breakpoints that are associated with Ada tasking 
exception events are' antomaticaily established. These 

automatically during debugger initialization when the Ada Run-Time Library 
present. 

When you enter a SHOW BREAK command under these conditions, the following 
breakpoints are displayed: 

DBG> SHOW BREAK . npvf-FPTTON TERMINATED" for any value 

Predefined £eak?oSt on ADA event "DEPENDENTS_EXCEPTION" for any value 
DBG> 

E.1.10 Monitoring Exceptions 

The debugger recognizes three kinds of exceptions in Ada programs. 

. A user-defined exception-an exception declared with the Ada reserved word 
exception in an Ada compilation unit 

• An Ada predefined exception, such as PROGRAM_ERROR or CONSTRAINT. 
ERROR 

• Any other (non-Ada) exception or VMS condition 

The following sections explain how to monitor such exceptions. 

E.1.10.1 Monitoring A y ^^ command enables you to set a breakpoint on 

Inv exception orWMS condition. This includes certain VMS conditions that are 
simaled biternally within the VAX Ada run-time library. These condit™ns are an 
implementation mechanism—they do not represent program fail ur es, and y 
rannot be handled by Ada exception handlers. If these conditions appear while 
—elbuS Jour program, you may want to consider speciiymg tire krnd of 
actions whfn Siting breakpoints (see Section E.l.10.2 and Section E.l.10.3). 

The following example shows a tracepoint occurring for anAda CONSTRAINT. 
ERROR exception as the result of a SET TRACE/EXCEFTION debugger 
command: 
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DBG> SET TRACE/EXCEPTION 
DBG> GO 


%ADA-F-CONSTRAINT_ERRO, CONSTRAINT ERROR 
ADA-I-EXCRAIPRI, Exception raised prior to PC = 00000A7C 
trace on exception preceding ADA$RAISE\ADA$RAISE_CONDITION.%LINE 333 + 12 ) 


ISM.'SElS* SH0W < f LLS comn,and displays a tra “ bad[ of the 
“ bPr0gram " heM ‘ he occurre d or to which the 

DBG> SET BREAK/EXCEPTION DO (SHOW CALLS) 

DBG> GO 


line 

rel PC 

abs PC 

17 

00000015 

000008AF 

19 

000000AE 

00000BAD 


00000009 

00000809 


00000054 

00000C36 


00000000 

000398BE 


0000001B 

0000081B 


0000002F 

00000C21 


PSL=03C000A2 T hrMi<- arithmet: '' C ' trap ' * nte 9 er divide by zero at PC=000008AF 
L 03C000 2 b ^ r ° n x ®^eption preceding SYSTEM_OPS.DIVIDE.%LINE 17+6 ' 

module name routine name 

*SYSTEM_OPS DIVIDE 

♦PROCESSOR PROCESSOR 

*ADA$ELAB_PROCESSOR 

ADA$ELAB_PROCESSOR 
LIB$INITIALIZE 

SHARE$ADARTL 
*ADA$ELAB_PROCESSOR 

ADA$ELAB_PROCESSOR 
LIBSINITIALIZE 

In this example, the VAX condition SS$ INTDIV is raised at lino i n - 
subprogram DIVIDE in the package SYSTEM.OPS. The example shows an 
important effect: some VAX conditions (such as $SS INTDIV) are treated as 
being equivalent to some Ada predefined exceptions." d 

bvthT^nndv ° f u condition and an Ada predefined exception is performed 
an exception^provided by VAX Ada for any frame that includes 

irSet«r te,n condition code name ' “ d - *• 

Monitoring Specific Exceptions 

Whenever an exception is raised, the debugger sets the following built-in symbols 
%EXC_FACILITY A string that names the facility that issued the exception The 

SSSKTiStf* p " dafl ” ed *»< — dean 
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%ADAEXC_NAME 


%EXC_NUM 

%EXC_SEVERITY 


%FXC NAME An uppercase string that names the exception. If the exception 

%EXC_NAME rai Ada predetaed Uon its nmy^ro-ated 

if u exceeds 15 characters. For example, CONS1KAIJN 
ERROR is truncated to CONSTRAINT.ERRO. If the exception 
is a user-defined exception, %EXC_NAME contains the stnng 
"EXCEPTION", and the name of the user-defined exception is 
contained in %ADAEXC_NAME. 

If the exception raised is user-defined, %ADAEXC_NAME contains 
a string that names the exception, and %EXC_NAME contains 
the string "EXCEPTION". If the exception is not user-defined, 

% AD AEXC_NAME contains a null string, and the name ot t e 
exception is contained in %EXC_NAME. 

The number of the exception. 

A string that gives the exception severity level (F, E, W, I, S, or ?). 

E 1 10 3 Monitoring Handled Exceptions and Exception Handlers . , 

The SET BREAK/EVENT and SET TRACE/EVENT commands enable you to set 
breakpoints and tracepoints on exceptions that are about to be hand e y 
exceptio^handlers. These commands allow you to observe the execution of each 
Ada exception handler that gains control. 

You can specify two event names with these commands-HANDLED and 
HANDLED_OTHERS: 

Triggers when an exception is about to be handled in some Ada 
exception handler, including an others handler. 

Triggers only when an exception is about to be handled in an 
others Ada exception handler. 

For example, the following command sets a breakpoint that triggera whenever an 
exception is about to be handled by an Ada exception handler. 

DBG> SET BREAK/EVENT=HANDLED 

When the breakpoint triggers, the debugger identifies the exceptaontlxat is about 
to be handled and the exception handler that is about to be execu . 
then use that information to set a breakpoint on a particular han or y 
enter the GO command, and see which Ada handler next attempts to handle 

exception. For example: 

DBG> GO 


HANDLED 

HANDLED.OTHERS 


E.1.11 


break on Ada event HANDLED 

task %TASK 1 is about to handle an exception 
The Ada exception handler is at: PROCESSOR.tLINE 21 
SADA-F-CONSTRAINT_ERRO, CONSTRAINT ERROR _ 

-ADA-I-EXCRAIPRI, Exception raised prior to PC 0 
DBG> SET BREAK PROCESSOR.%LINE 21; GO 

Examining and Manipulating Data 

When examining and manipulating data, note the following considerations: 

. Before vou can examine or deposit into a nonstatic variable (any variable not 
toS package), its defining subprogram, task, and so on, must 

be active on the call stack. 
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• Before you can examine, deposit, or evaluate an Ada subprogram formal 
parameter or an Ada vanable, the parameter or variable must be elaborated. 
In other words, you should step or otherwise move execution past the 
parameter or variable’s declaration. The value contained in any variable or 
tormal parameter whose declaration has not been elaborated might be invalid. 

In most cases, the debugger enables you to specify variables and expressions 
m debugger commands exactly as you would specify them in the source code 
o the P^^am, including use of qualified expressions. (See Section E.1.1 and 
Section E.1.2.) The following sections discuss some additional points about 
debugger support for records and access types. 

E.1.11.1 Records 

Note the following points about debugger support for records: 

With certain Ada record variables, the debugger fails to show the record 
components correctly (possibly with a NOACCESSR error message) when the 
type declaration is in a different scope than the record (symbol) declaration. 

With variant records, the debugger lets you examine or assign a value to 
a component of a variant part that is not active. But because this is an 
illegal action in Ada, the debugger also issues an informational message. For 

l xam l le - a f ume that record REC1 has a variant field named STATUS and 
that the value of STATUS is such that REC1.COMP3 is inactive: 

DBG> EXAMINE REC1.C0MP3 

%DEBUG-I-BADDISCVAL, incorrect value of 1 in discriminant 
field STATUS 
MAIN.REC1.C0MP3: 438 

E.1.11.2 Access Types 

Note the following points about debugger support for access types: 

The debugger does not support allocators, so you cannot create new access 
objects with the debugger. 

u ° U spe “^ the name of an access object with the EXAMINE command 
the debugger displays the memory location of the object it designates. 

To examine the value of a designated object, you must use selected component 
notation specifying .ALL. For example, to examine the value of a record 
access object designated by A: 

DBG> EXAMINE A.ALL 
EXAMPLE.A.ALL 

NAME(1..10): "John Doe " 

AGE : 6 

NEXT: 1462808 

To examine one component of a designated object, you can omit .ALL from the 
selected component syntax. For example: 

DBG> EXAMINE A.NAME 

EXAMPLE.A.ALL.NAME(1..10): "John Doe " 

The following example shows the debugger support for incomplete types. 

Consider the following declarations. 
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package P is 

type T is private; 
private 

type T_TYPE; 

type T is access T_TYPE; 
end P; 

package body P is 
type T_TYPE is 
record 

A: NATURAL := 5; 

B: NATURAL := 4; 

end record; 

T REC: T TYPE; 

T PTR: T ;= new T_TYPE'(T_REC); 

end P; 

with P; use P; 
procedure INCOMPLETE is 
VAR: T; 
begin 


end INCOMPLETE; 

The debugger does not have complete information about the type T, so you cannot 
manipulate the variable VAR. However, the debugger does have information about 
objects declared in the package body P. Thus, you can manipulate the variables 

T PTR and T REC. 


E.1.12 Module Names and Path Names 

The names of Ada debugger modules are the same as the names of the 
corresponding compilation units, with the following provision To eliminate 
ambiguity, an underscore character (_) is appended to a sp^ 
to distinguish it from its body name. For example, TEST (bo y), - 

(specification). To determine the exact names of the modules in your program, 
use the SHOW MODULE command. 

When specifying path names, in most cases you do not have to type the trailing 
underscore character to distinguish a specification from its body. The debugger 
can usually distinguish the two from the context. Therefore, use this naming 
convention only if needed to resolve an ambiguity. 

When the debugger language is set to Ada, the debugger generdly constructs 
path names that follow the Ada rules, using selected component notation to 
separate path name elements (with other languages, a backslash is used to 
separate elements). For example: 


! A1 is declared in the package specification of unit TEST 
i B1 is declared in the package body of unit TEST 


TEST_.A1 
TEST.B1 

The maximum length that you can specify for a subunit path name (expanded 
name) is 247 characters. 

When a use clause makes a symbol declared in a package directly visible outside 
the package, you do not need to specify an expanded nam e (package-name.symbol) 
to refer to the symbol, either in the program itself or in debugger commands. 

The SHOW SYMBOL/USE_CLAUSE command identifies any package (library 
or otherwise) that a specified block, subprogram, or package mentions in a use 
clause. If the entity specified is a package (library or otherwise), the command 
also identifies any block, subprogram, package, and so on, that names the 
specified module in a use clause. For example: 
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dbg> show symbol/use clause b 

package spec B_ 
used by: F 
uses: A__ 

L a J b6en ! S8i f ied t0 a lo °P statement or declare block in the source 
1 th6 debu , gger dlspla y s the label; otherwise, the debugger displays LOOP$n 
for a loop statement or BLOCK$n for a declare block, where n is the line 
number at which the statement or block begins. 

E.1.13 Symbol Lookup Conventions 

you d ° no * ^ a path Mme «Ad> 

expanded name), the debugger searches the Run-Time Symbol Table as follows. 

1. The debugger looks for the symbol within the module (compilation unit) 

unwinding the current PC value (where execution is currently suspended). 

2. If the symbol is not found, the debugger then searches any package that 

“ Zlt ? a US ! daUS f Tha debu ^ r d ° as “* distinguish Stwin 
a library package and a package whose declaration is in the same module 

uacWs SC ° Pe r !f° n u If the Same Symbo1 is declared in two or more 
J a J, g S , tbat are visible, the symbol is not unique (according to Ada rules) 
and the debugger issues a message like the following: 

%DEBUG-E-NOUNIQUE, symbol 'X' is not unique 


3. 


SiSr 1116 debUgSar 8earehM 4116 ““ atai * “«• “‘her 


E.1.14 Setting Modules 


When you or the debugger sets an Ada module, by default the debugger also 

withfrTtb re at ? d ,” ™ odule ~ that is > an y module whose symbols should be visible 
within the module being set. Such modules are related to the one being set 
through either a with clause or a subunit relationship. g 

f alat , ed “odnje setting takes place as follows. If Ml is the module that is being 
set, then the following modules are considered related and are also set: § 

aScatSTny^' debUggW ^ “*■ the ““*■*“* “brary 
' P f a“t of,hfp“a“L‘ he debWr a ‘ S ° S6tS ^ Paren ‘ “ nit 3nd - tharefere . 

If Mi mentions a library package PI in a with clause, the debugger also sets 

set h? G k f e * th f the bod y of P1 nor any possible subunits of PI are 

set, because symbols declared within them should not be visible outside. 

a package P2 in a with cIa nse, the debugger 
PS in n wHh T 6 ^ 10 ^ l Likewis6 ’ if P2 ’ s specification mentions a pfckage 
Tnee fi 7 th C !? U ,f ’ ^ debu Sg er also sets P3’s specification, and so on The 
pecifications of all such library packages are set so that you can access data 

Xr p Tkages r example ’ reC ° rd COmponents) that ma y ha ™ declared in 

™® nti01 ? s a librar y subprogram in a with clause, the debugger does 
not set the subprogram. Only the subprogram name needs to be visible in 
Ml (no declaration within a library subprogram should be visible outside 
the subprogram). Therefore, the debugger inserts the name of the library 
subprogram into the RST when Ml is set. ary 
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If debugger performance becomes a problem as more modules are set, .use the 
command SET MODE NODYNAMIC, which disables related module setting as 
well as dynamic module setting. You must then set individual modules explicitly 
with the SET MODULE command. 

By default, the SET MODULE command sets related modules simultaneously 
with the module specified in the command. 

SET MODULE/NORELATED sets only the modules you specify explicitly. 

!!wever ifyouuse SET MODULE/NORELATED, you may find that a symbol 
which is’declared in another unit and which should be v 181 ^ ^ pomt o 
execution is no longer visible; or that a symbo which should be hidden by 
redeclaration of that same symbol is now visible. 

The CANCEL MODULE/NORELATED command deletes from the RST only the 
modules you specify explicitly. The CANCEL MODULE/RELATED command 
which is the default, deletes related modules in a manner consistent with 
intent of Ada’s scop^ and visibility rules. The exact effect depends on module 

relationships. 

For example, consider the following Ada code: 

PI is a library package specification, and PI is its body. The specification Pl_ 
mentions the library package specification P3_ in a with clause. Then. 

• CANCEL MODULE/RELATED P3_ deletes only P3_. 

• CANCEL MODULE/RELATED Pl_ deletes Pl_ and P3_ (but P3_ is not 
deleted if it is directly related to another set module). 

. CANCEL MODULE/RELATED PI deletes PI, Pl_, and P3 (but neither 
Pl_ nor P3_ is deleted if either one is directly related to another set module). 

Similarly, consider the following set of subunits: 

P4.SUB1.SUB2 is a subunit of P4.SUB1, which is a subunit of P4. Then: 

. CANCEL MODULE/RELATED P4.SUB1.SUB2 deletes P4.SUB1.SUB2. 

• CANCEL MODULE/RELATED P4.SUB1 deletes P4.SUB1 and 
P4.SUB1.SUB2. 

• CANCEL MODULE/RELATED P4 deletes P4, P4.SUB1, and P4.SUB1.SUB2. 

E.1.14.1 Wemi^mg Rdiat MODULE/RELATED command identifies the modules that 

TrtlaSd to a specified module as defined in Section E.1.14. . The command 
shows the modules that are automatically set when a given m° dul « “ set J he 
SHOW MODULE/RELATED command also shows the modules that may be 
affected when you enter the CANCEL MODULE command. 

PL and P2_ are considered directly related to PI. P3_ is considered related to PI 
(by way of Pl_). 

The SHOW MODULE/RELATED command, applied to package body PI, would 
display information like the following. 
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symbols 

yes 

size 

868 

relationship 

yes 

884 

withed 

yes 

916 

withed 

yes 

868 

withed 

bytes allocated: 

109512. 
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DBG> SHOW MODULE/RELATED PI 
module name 

PI 

directly related modules: 

Pl_ 

P2__ 

related modules: 

P3 _ 

total ADA modules: 1. 

md thosT^ted'to pfZ r? all modules directly related 

dnatno s e related to PI are library packages. Note that the debugger treats the 

relahonship between a package body and its specification the samfas it treats 

the relationship between a unit and a package it mentions in a ^th cUuse 

Consider the following subunit structure: 

P4 and P4_ are a library package body and its specification, respectively. 

• P4.SUB1.SUB2 is a subunit of P4.SUB1, which is a subunit of P4. 

tatmatio" rS“® ”" mandl applied to P4 SUB1 - ^Play 

DBG> SHOW MODULE/RELATED P4.SUB1 
module name 

P4.SUB1 

directly related modules: 

P4 

P4.SUB1.SUB2 
related modules: 

P4_ 

total ADA modules: 1. 

SSSfJSS and directly related for subunite is anal ° 8ous 

Setting Modules for Package Bodies 

Modules for package bodies are not automatically set by the debugger. 

can debu^the th ? n J >dul ? f or librar y P«*age bodies yourself so that you 
package y " 8 Sabpr08rams **>"«« <■> *■» corresponding 

For more information on debugging Ada library packages, see Section E.1.8. 

Resolving Overloaded Names and Symbols 

^s^a^hkrthe^dLwing^^ 6 ^ Symb ° ls ’ the debugger issues a 

%DEBUG-E-NOTUNQOVR, symbol 'ADD' is overloaded 

use SHOW SYMBOL to find the unique symbol names 

If the overloaded symbol is an enumeration literal, you can use qualified 

For aa e * ampia «'****& 

If the overloaded symbol represents a subprogram or task accept statement 

comniwT ^ UmqUe name generated b y the compiler for the*debugger. The 
compiler always generates unique names for subprograms declared inlih™™ 

package bo^Uni 0 " 8 ’ nam6S might Iater be ^loaded in the 

package body. Unique names are generated for task accept statements and 


symbols 

size 

relationship 

yes 

828 


yes 

776 

parent 

yes 

836 

subunit 

yes 

728 

withed 

bytes allocated: 

191888. 
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subprograms declared in other places only if the task accept statements or 
subprograms are actually overloaded. 

Overloaded task accept statement names and subpr °gram narries are 
distinguished by a suffix consisting of two underscores followed by an integer 
that uniquely identifies the given symbol. You must use the unique naming 
notation in debugger commando to uniquely specify a 

overloaded. However, if there is no ambiguity, you do not need to use the umq 
name, even though one was generated. 

For example, suppose you are debugging a library package that contains two 

declarations of a^subprogram named SQUARES. One returns “ ZIsQuSe 
other a float type. If you try to set a breakpoint specifying the name SQUARE, 

you will receive an error like the following: 

DBG> SET BREAK SQUARE . 

%DEBUG-E-NOTUNQOVR, symbol 'SQUARE is overloaded 

use SHOW SYMBOL to find the unique symbol names 

Proceed as follows to resolve the ambiguity: 

1. Use the SHOW SYMBOL command to identify the overloaded symbols. For 
example: 

DBG> SHOW SYMBOL SQUARE 
overloaded symbol SYSTEM_OPS.SQUARE 

overloaded instance SYSTEM_OPS.SQUARE 1 
overloaded instance SYSTEM_0PS.SQUARE_2 

2 Use the EXAMINE/SOURCE command to determine which declaration an 
overloaded subprogram suffix number corresponds to. For example: 

DBG> EXAMINE/SOURCE SQUARE_1, SQUARE—2 

m ° dU 20: SYST function SQUARE (X: INTEGER) return INTEGER is 
module;SYSTEM_OPSon $QUARE (X; FIj0 ^ T) return FLOAT is 

3. You can then uniquely specify a particular declaration of an overloaded name. 
For example: 

DBG> SET BREAK SYSTEM_0PS.ADD_1, SQUARE_2 

E.1.16 CALL Command 

With Ada programs, you can use the CALL command rehab y on y wi 
Xro^Tat hasbeen exported. An exported subprogram must be a library 
subprogram or must be declared in the outermost declarative part of a library 
package. 

to modify the vaiue of a parameter. 

A CALL command may result in a deadlock if it is entered when the VAX Ada 
niu-hmeUbrm is executing. The VAX Ada run-time library routines acquire and 
release internal locks that allow the routines to operate in a tasking environmen . 
Deadlock can result if a subprogram called from the CALL command requires a 

resource that has been locked by an executing VAX ^ da Xmand 

To avoid this situation in a nontasking program, enter the CALL command 
immediately before or after an Ada statement has been executed. However this 
approach is not sufficient to assure that deadlock will not occur in a taski g 
program, as some other task may be executing a VAX Ada run-time library 
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routine at the time of the call. If you must use the CALL command in a tasking 

oH5r’oSpu?o^raMons a<U “ k *““ “ Ue<1 sub > >r °S r! “ **> *> W taking 


E.2 BASIC 


This section describes debugger support for BASIC. 

erators in Language Expressions 

Supported BASIC operators in language expressions follow: 

Kind Symbol Function --- 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition, String concatenation 

Infix 

~ 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

** 

Exponentiation 

Infix 

A 

Exponentiation 

Infix 

= 

Equal to 

Infix 

<> 

Not equal to 

Infix 

>< 

Not equal to 

Infix 

> 

Greater than 

Infix 

>= 

Greater than or equal to 

Infix 

=> 

Greater than or equal to 

Infix 

< 

Less than 

Infix 

<= 

Less than or equal to 

Infix 

=< 

Less than or equal to 

Prefix 

NOT 

Bit-wise NOT 

Infix 

AND 

Bit-wise AND 

Infix 

OR 

Bit-wise OR 

Infix 

XOR 

Bit-wise exclusive OR 

Infix 

IMP 

Bit-wise implication 

Infix 

EQV 

Bit-wise equivalence 

tructs in 

Language and Address Expressions 

Supported constructs in 

language and address expressions for BASIC follow: 

aymDOl 

Construct 


() 

Subscripting 


** 

Record component selection 
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E.2.3 Data Types 

Supported BASIC data types follow: 


BASIC Data Type VAX Data Type Name 

BYTE 

Byte Integer (B) 

WORD 

Word Integer (W) 

LONG 

Longword Integer (L) 

SINGLE 

F_Floating (F) 

DOUBLE 

D_Floating (D) 

GFLOAT 

G_Floating (G) 

HFLOAT 

H_Floating (H) 

DECIMAL 

Packed Decimal (P) 

STRING 

ASCII Text (T) 

RFA 

(None) 

RECORD 

(None) 

Arrays 

(None)______ 


E.2.4 Compiling for Debugging 

If vou make changes to a program in the VAX BASIC environment and attempt to 
compile the program with the /DEBUG qualifier without first saving or replacing 
the program, VAX BASIC signals the error “Unsaved changes no source hne 
debugging available.” To avoid this problem, save or replace the program, and 
then recompile the program with the /DEBUG qualifier. 

E.2.5 Constants ,, . 

BASIC constants of the forms [radix]“numeric-string [type] (sue 
“ 12 . 34 ”GFLOAT) or n% (such as 25% for integer 25) are not supported in 

debugger expressions. 

E.2.6 Evaluating Expressions 

Expressions that overflow in the BASIC language do not necessarily overflow 
P i k v the debugger The debugger tries to compute a numerically 

rules Si far overflows. This difference is 

particularly likely to affect DECIMAL computations. 

E.2.7 Line Numbers 

The sequential line numbers that you refer to in a debugging rnssmu ®d tlmt 
are displayed in a source code display are those generated by the compiler Wh 
a VAX BASIC program includes or appends code from another file, the include 
lines of code are also numbered in sequence by the compiler. 

E 2 8 Stepping into Routines 

The STEP/INTO command is useful for examining external functions^However, 
if vou use this command to stop execution at an internal subroutine or a DEF, 
fhe debugg^ initially steps into Run-Time Library (RTL) routines, prtmdmg you 
with no useful information. In the following example, execution is suspended a 
line 8, at a call to Print_routine: 
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~> 8 GOSUB Print routine 

9 STOP 


20 

21 

22 

23 

24 

25 


Print_routine: 

IF Competition = Done 

S S "The gl^esM 6 " “ ' Winnin ^ic k et 
END IF 
RETURN 


enter the SrmanlsCT BEF'AK P “ the rout “ e W *1 (for example, 

E.2.9 Symbolic References 

All variable and label names within a single VAY raQT r 1 . , 

unique. Otherwise the debugger * 

E.2.10 Watchpoints 

COMMO^ C I kS» U «!?“ e ‘ *. 7“ POint only °” "tables that are declared in 

variables explicitly declar"fte DeSSS'sS^T “* WatehP ° in ‘ S “ 

E.3 BUSS 

This section describes debugger support for BLISS. 

E.3.1 Operators in Language Expressions 

Supported BLISS operators in language expressions follow: 



Kind 

Prefix 

Prefix 

Prefix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 


/ 

MOD 

A 

EQL 

EQLU 


Function 

Indirection 
Unary plus 

Unary minus (negation) 

Addition 

Subtraction 

Multiplication 

Division 

Remainder 

Left shift 

Equal to 

Equal to 
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Kind 

Symbol 

Function__ ____ 

Infix 

EQLA 

Equal to 

Infix 

NEQ 

Not equal to 

Infix 

NEQU 

Not equal to 

Infix 

NEQA 

Not equal to 

Infix 

GTR 

Greater than 

Infix 

GTRU 

Greater than unsigned 

Infix 

GTRA 

Greater than unsigned 

Infix 

GEQ 

Greater than or equal to 

Infix 

GEQU 

Greater than or equal to unsigned 

Infix 

GEQA 

Greater than or equal to unsigned 

Infix 

LSS 

Less than 

Infix 

LSSU 

Less than unsigned 

Infix 

LSSA 

Less than unsigned 

Infix 

LEQ 

Less than or equal to 

Infix 

LEQU 

Less than or equal to unsigned 

Infix 

LEQA 

Less than or equal to unsigned 

Prefix 

NOT 

Bit-wise NOT 

Infix 

AND 

Bit-wise AND 

Infix 

OR 

Bit-wise OR 

Infix 

XOR 

Bit-wise exclusive OR 

Infix 

EQV 

Bit-wise equivalence___- 


E.3.2 Constructs in Language and Address Expressions 

Supported constructs in language and address expressions for BLISS follow. 



Symbol 

U 

[fldname] 
<p,s,e> 


Construct 

Subscripting 
Field selection 
Bit field selection 


E.3.3 Data Types 

Supported BLISS data types follow: 


BLISS Data Type 

BYTE 

WORD 

LONG 

BYTE UNSIGNED 
WORD UNSIGNED 
LONG UNSIGNED 


VAX Data Type Name 

Byte Integer (B) 

Word Integer (W) 
Longword Integer (L) 
Byte Unsigned (BU) 

Word Unsigned (WU) 
Longword Unsigned (LU) 
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BLISS Data Type 

VECTOR 
BITVECTOR 
BLOCK 

BLOCKVECTOR 
REF VECTOR 
REF BITVECTOR 
REF BLOCK 
REF BLOCKVECTOR 


(None) 

(None) 

(None) 

(None) 

(None) 

(None) 

(None) 

(None) 


E.4 C 

This section describes debugger support for C. 

E.4.1 Operators In Language Expressions 

Supported C operators in language expressions follow: 



Kind 

Prefix 

Prefix 

Prefix 

Prefix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Prefix 

Infix 

Infix 

Infix 

Prefix 

Infix 

Infix 


« 

» 

{—• 

> 

>= 


Function 

Indirection 
Address of 
size of 

Unary minus (negation) 

Addition 

Subtraction 

Multiplication 

Division 

Remainder 

Left shift 

Right shift 

Equal to 

Not equal to 

Greater than 

Greater than or equal to 

Less than 


<= 

Less than or equal to 

- (tilde) 

Bit-wise NOT 

& 

Bit-wise AND 

1 

Bit-wise OR 

A 

Bit-wise exclusive OR 

I 

Logical NOT 

&& 

Logical AND 

1 1 

Logical OR 


E-23 




Summary of Debugger Support for Languages 
E.4C 


/. as the comment delimiter. The comment contmues 0 the end of thecmrent 
r / a motr'V.incr */ is neither needed nor recognized.) To permit debugger g 
files to be used as debugger input, the debugger still recognizes ! as a commen 
delimiter if it is the first nonspace character on a line. 

S^uage^^resskM^ and de^^ge^ad^'ess^^ires^m^^n^ad^'ess^^ress^isi 
prefois synonymous to prefix or when the language is set to C. 

The debugger does not support any of the assignment operators in C ( or any other 

lan"n -der to prevent unhanded —Tb 

»coS^Sr— do eo with an explicit DEPOSiT 

command. 

E.4.2 Constructs In Language and Address Expressions 

Supported constructs in language and address expressions for C follow. 



Subscripting 

Structure component selection 
Pointer dereferencing 


E.4.3 Data Types 

Supported C data types follow: 


int 

unsigned int 
short int 

unsigned short int 
char 

unsigned char 

float 

double 

enum 

struct 

union 

Pointer Type 
Array Type 


E.4.4 Case Sensitivity 


VAX Data T ype Name 

Longword Integer (L) 
Longword Unsigned (LU) 
Word Integer (W) 

Word Unsigned (WU) 
Byte Integer (B) 

Byte Unsigned (BU) 
F_Floating(F) 
D_Floating (D) 

(None) 

(None) 

(None) 

(None) 

(None) 


Symbol ^names arc case sensitive for language C meaning that uppercase and 
lowercase letters are treated as different characters. 
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E.4.5 Static and Nonstatic Variables 

SS St ° ra8e Cla8S6S "* aU ° Cated StatMy: «W-M< 

“ °/ th f f ° ll0wing storage classes are allocated nonstatically (on the stack 
terS): a + Ut0 and register - Such variables can be accessed oSy when 
their defining routine is active (on the call stack). 

E.4.6 Scalar Variables 

Jou Vari fu hS 0t any c ty <* ta debugger commands exactly as 

you would specify them in the source code of the program. 

Md pointers^ ParagTaphs pr0vide additiwMl information about char variables 
rhrractera'To^snlartb 16111 ^' b « debu8ger as ^ integers, not ASCII 

“Sc^tSer 6 C0 ” tentS ° f 3 ° bar Variab ' e Ch “ a *«—> y ~ —* 

DBG> EXAMINE/ASCII ch 
SCALARS\main\ch: "A" 

^,n^T St K U rf e ^ /ASCH qualifier when depositing into a char variable to 
translate the byte integer into its ASCII equivalent: 

DBG> DEPOSIT/ASCII ch = 'z' 

DBG> EXAMINE/ASCII ch 
SCALARS\main\ch: « z « 

Ass e ume°t^ n L1n ampl 7^ WS USC ° f P ° inter syn * ax with the EXAMINE command 
Assume the following declarations and assignments: 

static long li = 790374270 ; 
static int *ptr = sli; 


DBG> EXAMINE *ptr 
* SCALARS\main\pt r: 


790374270 


E.4.7 Arrays 


The debugger handles C arrays as for most other languages. That is you can 

pip in f an - 6n lre array a SS re S at e, a slice of an array, or an individual array 

i r * USmg array syntax (for exam Ple EXAMINE arr[3J). And you can deposit 
into only one array element at a time y deposit 


E.4.8 Character Strings 


?wfT tringSare implemented in C as null-terminated ASCII strings (ASCIZ 
o examine and deposit data in an entire string, use the /ASCIZ 
quaMer (abbreviated /AZ) so that the debugger can 

ushSTeT * U r eXamine and de P° sit individual characters in the string 

irS g i h i C u y subscnpting operators ([ ]). When you examine and de D osit g 
individual characters, use the /ASCII qualifier. P 

Assume the following declarations and assignments: 

static char *s = "vaxie"; 
static char **t = Ss; 
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The EXAMINE/AZ command displays the contents of the character string pointed 

to by *s and **t: 

DBG> EXAMINE/AZ *S 
*STRING\main\s: "vaxie" 

DBG> EXAMINE/AZ **t 
**STRING\main\t: "vaxie 

The DEPOSIT/AZ command deposits a new ASCIZ string in the 

to by *s. The EXAMINE/AZ command displays the new contents of the string. 

DBG> DEPOSIT/AZ *s = "VAX C" 

DBG> EXAMINE/AZ *s, **t 

*STRING\main\s: "VAX C" 

**STRING\main\t: "VAX C" 

You can use array subscripting to examine individual characters in the string 
, , a qptt values at specific locations within the string. When 

SttSStoSZSZfA - the /ASCII quabbe, A subsequent 
EXAMINE/AZ command shows the entire string containing the deposited va . 

DBG> EXAMINE/ASCII s[3] 

[3]: 

DBG> DEPOSIT/ASCII s[3] = 

DBG> EXAMINE/AZ *s, **t 
*STRING\main\s: "VAX-C" 

**STRING\main\t: "VAX-C" 

E 4 9 Structures and Unions 

You can examine structures in their entirety or on a member-by-member barns, 
and deposit data into structures one member at a time. 

Tb reference members of a structure or union, use the usual C syntax for such 

references. That is, if variable p is a pointer to a st ^ r ^2\Txr£v S to the 
member y of that structure with the expression p ->y. If variable x refers to t 
C of the storage allocated for a structure, you can refer to a member of that 

structure with the x.y expression. 

to both x.y and p ->y. 

. If only one of the members, y, belongs in the structure or union, x, that is the 
one that is referenced. 

. If only one of the members, y, is in the same scope as x, then that is the one 
that is referenced. 

x and y. 

The following example, which defines a structure and union, is used to show ow 
to access structures and unions and their elemen s. 
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main () 


static struct 


{ 


} 

union 


int im; 
float fm; 
char cm; 
unsigned bf 
sv, *p; 


3; 


int im; 
float fm; 
char cm; 

} uv; 

sv.im = -24; 
sv.fm = 3.0el0; 
sv.cm = 'a'; 
sv.bf = 7; 
p = &sv; 
uv.im = -24; 
uv.fm = 3.0el0; 
uv.cm = 'a'; 


/* Binary: 111 */ 


} 

main SH0W SYMB0L comman<1 *ow. the variables contained in the function 

DBG> SHOW SYMBOL * in main 
routine STRUCT\main 
data STRUCT\main\uv 

record component STRUCT\main\<generated name 0002>.im 
record component STRUCT\main\<generated"name _ 0002 > fm 

type r STRUCT\main\< TR ^ C ^^t na H n '' < enera ^ e< ^— na ^ _ ' ^ 

type STRUCT\main\<generated name 0002> 

data STRUCT\main\p 

data STRUCT\main\sv 

Itrnli COmponent STRUCT\main\<generated name 0001>.im 
record *° mP ° nent fRUCT\main\<generated-name-() 001 > £ 
record component STRUCT\main\<generated~name' 0001 > cm 

t^°1^sr ent ^ STRUcnmain \ <generat e d ~ n a--oooi>:b? 
type STRUCT\main\<generated_name__0001> 

Use the EXAMINE command with the name of the structure to disnlav all 

DBG> EXAMINE sv 
STRUCT\main\sv 
im: -24 

fm: 3.0000001E+10 
cm: 97 
bf: 7 

on fte P K^“inr^X a bit h M*,'h ,«?*' Z /ASCI1 qualifier 

use the/BINARY qualifier: P 7 fields ln their binary representation, 

DBG> EXAMINE/ASCII sv.cm 
STRUCT\main\sv.cm: "a" 

DBG> EXAMINE/BINARY sv.bf 
STRUCT\main\sv.bf: m 
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You deposit data into a structure one member at a time. To^deposit^ “£ther 

the %BIN keyword: 

DBG> DEPOSIT sv.im = 99 
DBG> DEPOSIT sv.fm =3.14 
DBG> DEPOSIT/ASCII sv.cm = ' z' 

DBG> DEPOSIT sv.bf = %BIN 010 
DBG> EXAMINE sv 
STRUCT\main\sv 

im: 99 

fm: 3.140000 
cm: 122 

Members of structures (and unions) can also be accessed by pointer, as shown in 

*p and p ->bf: 

DBG> EXAMINE *P 
*STRUCT\main\p 
im: 99 

fm: 3.140000 
cm: 122 
bf: 2 

DBG> EXAMINE/BINARY p ->bf 
STRUCT\main\p ->bf: 010 

meaningless: 

dbg> step 

stepped to STRUCT\main\ILINE 30 
30: uv.fm = 3.0el0; 

DBG> EXAMINE UV 
STRUCT\main\uv 

im: -24 

fm: -1.5485505E+38 
cm: -24 

This series of STEP and EXAMINE commands shows the content of the union as 
the different members are assigned values: 

DBG> STEP 

stepped to STRUCT\main\%LINE 31 
31: uv.cm = ' a'; 

DBG> EXAMINE uv.fm 

STRUCT\main\uv.fm: 3.0000001E+10 

DBG> STEP 

stepped to STRUCT\main\%LINE 32 
33: ) 

DBG> EXAMINE/ASCII uv.cm ^ 

STRUCT\main\uv.cm: "a" 

The following example, which defines a structure, is used to show debugger 

support for operators. 

main() 


int count, i = 1; 
char c = 'A'; 
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struct 

{ 

int digit; 
char alpha; 

} tbl [27], *p; 

for (count = 0; count <= 26; count++) 

tbl[count].digit = i++; 
tbl[count].alpha = c++; 

} 


The first EVALUATE command that follows uses C syntax to refer to the address 

aualifierto oht ** t0 f the second command, which uses the /ADDRESS 

qualifier to obtain the address of the variable. 

DBG> EVALUATE Stbl 
2146736881 

DBG> EVALUATE/ADDRESS tbl 
2146736881 

vaL Ca „ n ffte'memben VidUal member8 ° f “ tha dabu ^ 

DBG> EVALUATE tbl[2].digit 

V^en you perform pointer arithmetic, the debugger displays a message indicating 
the scale factor that has been applied. It then returns the address resulWfrom 

^s^r5'^’va A nS!r Uent EXAMINE COmmand at 11131 address 

DBG> EVALUATE tbl + 4 

ri'KgSS™’ P ° int " * dditi0n: SCale factor of 5 to 

2146736901 

DBG> EXAMINE 2146736901 
ARSTRUCT\main\tbl[4].digit: 5 

U,DATE “ mmand *° perfonn arithmatic <*”»*»“ «■> 

DBG> EVALUATE tbl[4].digit * 2 


The debugger enters a message when you use an unsupported operator: 

DBG> EVALUATE count++ 

IDEBUG-W-SIDEFFECT, operators with side effects not supported (++, ~) 

E.5 COBOL 

This section describes debugger support for COBOL. 
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E.5.1 Operators in Language Expressions 

Supported COBOL operators in language expressions follow: 


Function 

Unary plus 
Unary minus (negation) 
Addition 
Subtraction 
Multiplication 
Division 
Exponentiation 
Equal to 
Not equal to 
Greater than 
Greater than or equal to 
Less than 

Less than or equal to 
Logical NOT 
Logical AND 
Logical OR 


Kind 

Prefix 

Prefix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 

Infix 


NOT = 
> 

NOT < 
< 

NOT > 
NOT 
AND 
OR 


E.5.2 Constructs in Language and Address Expressions 

Supported constructs in language and address expressions for COBOL follow. 



E.5.3 Data Types 

Supported COBOL data types follow: 


COBOL Data Type 

COMP 
COMP 
COMP 
COMP-1 
COMP-2 
COMP-3 
INDEX 
Alphanumeric 
Records 


VAX Data Type Name 

Longword Integer (L,LU) 
Word Integer (W,WU) 
Quadword Integer (Q,QU) 
F_Floating(F) 
D_Floating (D) 

Packed Decimal (P) 
Longword Integer (L) 
ASCII Text (T) 

(None) 
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COBOL Data Type 

VAX Data Type Name 

Numeric Unsigned 

Numeric string, unsigned (NU) 

Leading Separate Sign 

Numeric string, left separate sign (NL) 

Leading Overpunched Sign 

Numeric string, left overpunched sign (NLO) 

Trailing Separate Sign 

Numeric string, right separate sign (NR) 

Trailing Overpunched Sign 

Numeric string, right overpunched sign (NRO) 

E.5.4 Source Display 


RFP? A b rmr ptmT t6Xt included in a Program with the COPY, COPY 
nr RPPr C JnS’° r RE , PL ^ CE statemen t- However, when COPY REPLACING 
f , REPL f‘ CE 1S used ’ the debugger shows the original source text instead of 

statement^ S ° UrCe generated by the C0PY REPLACING or REPLACE 

JrVport^ cannot show the original source lines associated with the code for 
^ith I RfIArtT'. ^ S 6 v the DATA SECTI0N s^ce ^es associated 
SnlaS rlport ”° aSSOdated '' dth ““ “Oe that 

E.6 DIBOL 

This section describes debugger support for DIBOL. 

E.6.1 Operators in Language Expressions 

Supported DIBOL operators in language expressions follow: 


Kind 

Symbol 

Function 

Prefix 

# 

Round 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

// 

Division with fractional result 

Infix 

•EQ. 

Equal to 

Infix 

.NE. 

Not equal to 

Infix 

.GT. 

Greater than 

Infix 

.GE. 

Greater than or equal to 

Infix 

.LT. 

Less than 

Infix 

.LE. 

Less than or equal to 

Infix 

.NOT. 

Logical NOT 

Infix 

.AND. 

Logical AND 

Infix 

.OR. 

Logical OR 

Infix 

.XOR. 

Exclusive OR 
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E.6.2 Constructs in Language and Address Expressions 

Supported constructs in language and address expressions for DIBOL follow: 

Symbol Construct_______ 

() Substring 

[ ] Subscripting 

Record component selection 

E.6.3 Data Types 

Supported DIBOL data types follow: 


DIBOL Data Type VAX Data Type Name 


11 

Byte Integer (B) 

12 

Word Integer (W) 

14 

Longword Integer (L) 

Pn 

Packed Decimal String (P) 

Pn.m 

Packed Decimal String (P) 

Dn 

Numeric String, Zoned Sign (NZ) 

Dn.m 

Numeric String, Zoned Sign (NZ) 

An 

ASCII Text (T) 

Arrays 

(None) 

Records 

(None) 

FORTRAN 

This section describes debugger support for FORTRAN. 


E.7.1 Operators in Language Expressions 

Supported FORTRAN operators in language expressions follow: 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 

— 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

** 

Exponentiation 

Infix 

// 

Concatenation 

Infix 

.EQ. 

Equal to 

Infix 

.NE. 

Not equal to 

Infix 

.GT. 

Greater than 

Infix 

.GE. 

Greater than or equal to 
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Kind 

Symbol 

Function 

Infix 

.LT. 

Less than 

Infix 

.LE. 

Less than or equal to 

Prefix 

•NOT. 

Logical NOT 

Infix 

•AND. 

Logical AND 

Infix 

.OR. 

Logical OR 

Infix 

•XOR. 

Exclusive OR 

Infix 

.EQV. 

Equivalence 

Infix 

.NEQV. 

Exclusive OR 


E.7.2 Constructs in Language and Address Expressions 

Supported constructs in language and address expressions for FORTRAN follow: 

Symbol Const ruct -- 

( ) Subscripting 

• _ Record c omponent selection 

E.7.3 Predefined Symbols 

Supported FORTRAN predefined symbols follow: 

Symbol D escription ~ -- 

.TRUE. Logical True 

•FALSE. Logical False 


E.7.4 Data Types 

Supported FORTRAN data types follow: 


FORTRAN Data Type 

LOGICAL* 1 

LOGICAL*2 

LOGICAL*4 

INTEGER*2 

INTEGER*4 

REAL*4 

REAL*8 

REAL*8 

REAL* 16 

COMPLEX*8 

COMPLEX* 16 


VAX Data Type Name 

Byte Unsigned (BU) 

Word Unsigned (WU) 
Longword Unsigned (LU) 
Word Integer (W) 
Longword Integer (L) 
F_Floating (F) 
D_Floating (D) 
G_Floating (G) 
H_Floating (H) 
F_Complex (FC) 
D_Complex (DC) 
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FORTRAN Data Type 

VAX Data Type Name 

COMPLEX* 16 

G_Complex (GC) 

CHARACTER 

ASCII Text (T) 

Arrays 

(None) 

Records 

(None) 


Even though the VAX data type coaes ioi - '— ’ ’ ,. 

used internally to describe the LOGICAL data types, the debugger 
compiler) treats LOGICAL variables and values as being signed when used 

language expressions. 

The debugger prints the numeric values of LOGICAL variables or expressions 
instead of TRUE, or .FALSE. Normally, only the low-orderbit. °f a LOGICAL 
variable or value is significant (0 is .FALSE, and 1 is .TRUE.). However, 

VAX FORTRAN does allow all bits in a LOGICAL value to be manipulated^ 
and LOGICAL values can be used in integer expressions. Fm to reason it 
is at times necessary to see the entire integer value of a LOGICAL variable 
expression, and that is what the debugger shows. 

COMPLEX constants such as (1.0,2.0) are not supported in debugger expressions. 

Floating point numbers of type REAL*8 and COMPLEX*16 may be represented 
by D_Floating or G_Floating depending on compiler switches. 

E.7.5 Initialization Code 

When you invoke the debugger for a program compiled with the or ^ o5>r<5 . 

/CHECK=UNDERFLOW or /PARALLEL qualifier, the following message appe . 

$ RUN FORMS 

VAX DEBUG Version 5.5 

IDEBUG-I-INITIAL, language is FORTRAN, module set to FORMS 
%DEBUG-I-NOTATMAIN , type GO to get to start of mam program 

DBG> 

The “NOTATMAIN” message indicates that execution is supended before the start 
tte Zn pragram, so thlt you can execute initialisation code under debugger 
cmtrol TVptag fte GO command places you at the start of the mam program. At 
that poinh type the GO command again to start program execution, as with other 
types of FORTRAN programs. 

E.8 MACRO-32 

This section describes debugger support for MACRO-32. 

E.8.1 Operators in Language Expressions 

Language MACRO does not have expressions in the same sense as hig - eve 
la ws. My assembly-time expressions and only a limited set of operators 
are^accepted. 1b permit the MACRO programmer to use expressions at debug- 
rime as freely as in other languages, the debugger acceptsa° f “P erators 
in MACRO language expressions that are not found m MA 
particular the debugger accepts a complete set of comparison and Boolean 
operators modeled after BLISS. It also accepts the indirection operator and the 

normal arithmetic operators. 
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Kind 

Symbol 

Function 

Prefix 

9 

Indirection 

Prefix 

. 

Indirection 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

MOD 

Remainder 

Infix 

9 

Left shift 

Infix 

EQL 

Equal to 

Infix 

EQLU 

Equal to 

Infix 

NEQ 

Not equal to 

Infix 

NEQU 

Not equal to 

Infix 

GTR 

Greater than 

Infix 

GTRU 

Greater than unsigned 

Infix 

GEQ 

Greater than or equal to 

Infix 

GEQU 

Greater than or equal to unsigned 

Infix 

LSS 

Less than 

Infix 

LSSU 

Less than unsigned 

Infix 

LEQ 

Less than or equal to 

Infix 

LEQU 

Less than or equal to unsigned 

Prefix 

NOT 

Bit-wise NOT 

Infix 

AND 

Bit-wise AND 

Infix 

OR 

Bit-wise OR 

Infix 

XOR 

Bit-wise exclusive OR 

Infix 

EQV 

Bit-wise equivalence 

tructs in Language and Address Expressions 

Supported constructs in language and address expressions for MACRO-32 follow: 

Symbol Construct " “ ---- 

□ 

Subscripting 

<p,s,e> 

Bitfield selection as in BLISS 


7 n ! n u Iormatlon generated by the MACRO assembler treats a label that 
wh f n!p° Wed by aa assembler directive for storage allocation as an array variable 
name is the label. This enables you to use the array syntax of a high-level 

language when examining or manipulating such data. g 

In the following example of MACRO source code, the label LAB4 designates 
hexadecimal data stored in four words: 

.WORD A X3F,5[2], A X3C 


LAB 4 
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The debugger treats LAB4 as an array variable. For example, the next command 
displays the value stored in each element (word): 

DBG> EXAMINE LAB4 
,MAIN.\MAIN\LAB4 


[01: 

003F 

[11: 

0005 

[21: 

0005 

[31: 

003C 


The next command displays the value stored in the fourth word (the first word is 
indexed as element “0”)*. 


DBG> EXAMINE LAB4[3] 
.MAIN.\MAIN\LAB4[3] : 

03C 

Data Types 


Supported MACRO-32 data types follow: 

MACRO-32 Data Type 

VAX Data Type Name 

(Not applicable) 

Byte Unsigned (BU) 

(Not applicable) 

Word Unsigned (WU) 

(Not applicable) 

Longword Unsigned (LU) 

(Not applicable) 

Byte Integer (B) 

(Not applicable) 

Word Integer (W) 

(Not applicable) 

Longword Integer (L) 

(Not applicable) 

F_Floating (F) 

(Not applicable) 

D_Floating (D) 

(Not applicable) 

G_Floating (G) 

(Not applicable) 

H_Floating (H) 

(Not applicable) 

Packed decimal (P) 

Pascal 


This section describes debugger support for Pascal. 


E.9.1 Operators in Language Expressions 

Supported Pascal operators in language expressions follow: 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 

— 

Unary minus (negation) 

Infix 

+ 

Addition, concatenation 

Infix 

— 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Real division 

Infix 

DIV 

Integer division 

Infix 

MOD 

Modulus 


E-36 













Summary of Debugger Support for Languages 

E.9 Pascal 

Kind Symbol Function 

Remainder 
Exponentiation 
Set membership 
Equal to 
Not equal to 
Greater than 
Greater than or equal to 
Less than 

Less than or equal to 
Logical NOT 
Logical AND 
Logical OR 

The typecast operator (::) is not supported in language expressions. 

E.9.2 Constructs In Language and Address Expressions 

Supported constructs in language and address expressions for Pascal follow: 

Symbol Construct ~ ~ ---- 

[ ] Subscripting 

Record component selection 
A Pointer dereferencing 

E.9.3 Predefined Symbols 

Supported Pascal predefined symbols follow: 

Symbol M eaning "- 

TRUE Boolean True 

FALSE Boolean False 

NIL Nil pointer 

E.9.4 Built-In Functions 

Supported Pascal built-in functions follow: 

Symbol Meaning “ - 

SUCC Logical successor 

PRED Logical predecessor 


Infix 

REM 

Infix 

** 

Infix 

IN 

Infix 

= 

Infix 

<> 

Infix 

> 

Infix 

>= 

Infix 

< 

Infix 

<= 

Prefix 

NOT 

Infix 

AND 

Infix 

OR 
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E.9.5 Data Types 

Supported Pascal data types follow. 


Pascal Data Type 

VAX Data Type Name 

INTEGER 

Longword Integer (L) 

INTEGER 

Word Integer (W,WU) 

INTEGER 

Byte Integer (B,BU) 

UNSIGNED 

Longword Unsigned (LU) 

UNSIGNED 

Word Unsigned (WU) 

UNSIGNED 

Byte Unsigned (BU) 

SINGLE 

F^Floating (F) 

DOUBLE 

DJFloating (D) 

DOUBLE 

G_Floating (G) 

QUADRUPLE 

H_Floating (H) 

BOOLEAN 

(None) 

CHAR 

ASCII Text (T) 

VARYING OF CHAR 

Varying Text (VT) 

SET 

(None) 

FILE 

(None) 

Enumerations 

(None) 

Subranges 

(None) 

Typed Pointers 

(None) 

Arrays 

(None) 

Records 

(None) 

Variant records 

(None) 


The debugger accepts Pascal set constants such as [1,2,5,8..10] or [RED, BLUE] 
in Pascal language expressions. 


E.9.6 Additional Information 

In general, you can examine, evaluate, and deposit into variables, record 
fields, and array components. An exception to this occurs under the following 
circumstances: if a variable is not referenced in a program, the VAX Pasca 
compiler might not allocate the variable. If the variable is not allocated and you 
try to examine it or deposit into it, you will receive an error message. 

When you deposit data into a variable, the debugger truncates the Wgh-order 
bits if the value being deposited is larger than the variable; it fills the high-order 
bits with zeros if the value being deposited is smaller than the variable. If the 
deposit violates the rules of assignment compatibility, the debugger displays an 
informational message. 

You can examine and deposit into automatic variables (within any active block); 
however, because automatic variables are allocated in stack storage and are 
contained in registers, their values are considered undefined until the variables 
are initialized or assigned a value. 
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E.9.7 Restrictions 

Restrictions in debugger support for Pascal are as follows. 

lengthTrodv ^ 0 ° F u HAR string - But you cannot examine 

VAR “r B0D ^ „ usmgtl } e normal language syntax. For example, if 
VARS is the name of a string variable, the following commands are not supported: 

DBG> EXAMINE VARS.LENGTH 
DBG> EXAMINE VARS.BODY 

To examine these fields, use the techniques illustrated in the following examples. 


Use 

Instead of 


EXAMINE/WORD VARS 

EXAMINE/ASCII VARS+2 

EXAMINE VARS.LENGTH 

EXAMINE VARS. BODY 



E.10 PL/I 

This section describes debugger support for PL/I. 

E.10.1 Operators in Language Expressions 

Supported PL/I operators in language expressions follow: 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

** 

Exponentiation 

Infix 

1 1 

Concatenation 

Infix 

= 

Equal to 

Infix 

A_ 

Not equal to 

Infix 

> 

Greater than 

Infix 

>= 

Greater than or equal to 

Infix 

A < 

Greater than or equal to 

Infix 

< 

Less than 

Infix 

<= 

Less than or equal to 

Infix 

A > 

Less than or equal to 

Prefix 

A 

Bit-wise NOT 

Infix 

& 

Bit-wise AND 

Infix 

1 

Bit-wise OR 
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E.10.2 Constructs in Language and Address Expressions 

Supported constructs in language and address expressions for PL/I follow: 


Symbol Construct 

() Subscripting 


Structure component selection 

_> Pointer dereferencing 


Types 


Supported PL/I data types follow: 

PL/I Data Type 

VAX Data Type Name 

FIXED BINARY 

Byte- (B), Word- (W), or Longword- (L) Integer 

FIXED DECIMAL 

Packed Decimal (P) 

FLOAT BIN/DEC 

F_Floating (F) 

FLOAT BIN/DEC 

DJFloating (D) 

FLOAT BIN/DEC 

G_Floating (G) 

FLOAT BIN/DEC 

H_Floating (H) 

BIT 

Bit (V) 

BIT 

Bit Unaligned (VU) 

CHARACTER 

ASCII Text (T) 

CHARACTER VARYING 

Varying Text (VT) 

FILE 

(None) 

Labels 

(None) 

Pointers 

(None) 

Arrays 

(None) 

Structures 

(None) 


E.10.4 Static and Nonstatic Variables 

Variables of the following storage classes are allocated statically: STATIC, 
EXTERNAL, GLOBALDEF, and GLOBALREF. 

Variables of the following storage classes are allocated nonstatically (on the 
stack or in registers): AUTOMATIC, BASED, CONTROLLED, DEFINED, and 
PARAMETER. 

E.10.5 Examining and Manipulating Data 

This section gives examples showing use of the EXAMINE command with PL/I 
data types. It also highlights aspects of debugger support that are specific 

PL/I. 
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E.10.5.1 EXAMINE Command Examples 

PM di 1 t < n"pes Xan “ >leS Sh ° W " S " ° f ‘ he EXAMINE “"'■"and with a few selected 

Examine the value of a variable declared as FIXED DECIMAL (10,5): 

DBG> EXAMINE X 
PR0G4\X: 540.02700 

Examine the value of a structure variable: 

DBG> EXAMINE PART 

MAIN_PR0G\INVENTORY_PROG\PART 

ITEM: "WF-1247" 

PRICE: 49.95 

IN_ST0CK: 24 

vZS e Jksf 1 ^ variabIe <note that debugser <Usi>lays the 

DBG> EXAMINE Q 
MAIN\Q: "666.3330" 

ac X ce“S lndd a il ? U nl a 0f t a h POin , ter i§ the Virtual address of the variable it 

defaults 6 6 m hexadecimal radix instead of decimal (the 

DBG> EXAMINE/HEXADECIMAL P 
PR0G4\SAMPLE.P: 0000B2A4 

Examine the value of a variable with the BASED attribute; in this case the 
variable X has been declared as BASED(PTR), with PTR its pointer: ’ 

DBG> EXAMINE X 
PR0G\X: "A" 

Examine the value of a variable X declared as BASED with a variable PTR 
declared as POINTER; here, PTR is associated with X by tL follo^ng 

example): ^ ° f X " g ^ declared as BASED(PTR) as in the preceding 

ALLOCATE X SET (PTR); 

In this case, you examine the value of X as follows: 

DBG> EXAMINE PTR->X 
PR0G6\PTR->X: "A" 

E. 10.5.2 Notes on Debugger Support 

Note the following points about debugger support for PL/I. 

You cannot use the DEPOSIT command with entry or label variables or formats 
or wi entire arrays or structures. You cannot use the EXAMINE command with 
, ”.Z.° r at VanablK or fomiats ; "»> ‘he EVALUATE/ADDRESS command 

You cannot use the EXAMINE command to determine the values or attributes 
of global literals (such as GLOBALDEF VALUE literals) because they are static 
expressions. Use the EVALUATE command instead. y 

You cannot use the EXAMINE, EVALUATE, and DEPOSIT commands with 

^ERDSITTbu^M^EXMIINE? 6 ^ 1 " 68 Y ° U ? 3n : however > use EVALUATE and 
constantis the ~ 
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Note that an uninitialized automatic variable does not have valid contents un 1 
after a value has been assigned to it. If you examine it before that point, the 
value displayed is unpredictable. 

You can deposit a value into a pointer variable either by depositing another 
pointer’s value into it, thus making symbolic reference to both pointers, or by 
depositing a virtual address into it. (You can find out the virtual address of a 
variable by using the EVALUATE/ADDRESS command, and then deposit that 
address into the pointer.) When you examine a pointer, the debugger displays its 
value in the form of the virtual address of the variable that the pointer points to. 

The debugger treats all numeric constants of the form n or n.n in PL/I language 
expressions as packed decimal constants, not integer or floating-point constants, 
in order to conform to PL/I language rules. The internal representation of 10 is 
therefore 0C01 hexadecimal, not 0A hexadecimal. 

You can enter floating-point constants using the syntax nEn or n.nEn. 

There is no PL/I syntax for entering constants whose internal representation is 
Longword Integer. This limitation is not normally significant when debugging, 
since the debugger supports the PL/I type conversion rules. Uwevvc * “ 
possible to enter integer constants by using the debuggers %HEX, %OCT, and 
%BIN operators, because nondecimal radix constants are assumed ° 

RTNARY For example, EVALUATE/HEXADECIMAL 53 + %HEX 0 displays 00000035. 


E.11 RPGII 

This section describes debugger support for RPG II. 

E.ii.l Operators in Language Expressions 

The following operators are supported in language expressions when the language 
is set to RPG II: 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

= 

Equal to 

Infix 

NOT = 

Not equal to 

Infix 

> 

Greater than 

Infix 

NOT < 

Greater than or equal to 

Infix 

< 

Less than 

Infix 

NOT > 

Less than or equal to 

Prefix 

NOT 

Logical NOT 

Infix 

AND 

Logical AND 

Infix 

OR 

Logical OR 
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E.11.2 Constructs in Language and Address Expressions 

Supported constructs in language and address expressions for RPG II follow: 


Symbol Construct 

( ) Subscripting 

Types 


Supported RPG II data types follow: 

RPG II Data Type 

VAX Data Type Name 

Longword binary numeric 

Longword Integer (L) 

Word binary numeric 

Word Integer (W) 

Packed decimal 

Packed Decimal (P) 

Character 

ASCII Text (T) 

Overpunched decimal 

Right Overpunched Sign (NRO) 

Arrays 

(None) 

Tables 

(None) 


E.11.4 Setting Breakpoints or Tracepoints 

Witli RPG II programs, you can set breakpoints using source line numbers, logic 
cycle labels, user-defined tag names, and subroutine labels. Debugging RPG II 
programs is somewhat different from debugging programs in other languages, 

and the following paragraphs explain where and how you can set breakpoints or 
tracepoints. 

E.11.4.1 Setting Breakpoints or Tracepoints Within Specifications 

The following paragraphs describe where you can set breakpoints (or tracepoints) 
in specifications, using line numbers. 

The RPG II program cycle determines the order in which program lines are 
processed. When setting breakpoints or tracepoints, you can reference the line 
numbers that RPG II assigns to your program and appear in a listing file or in a 
ebugger source display. The line numbers you specify in columns 1 through 5 of 
a specification are not used. 

The compder assigns line numbers only to certain specifications at specific points 
in the logic cycle; therefore, you can specify a breakpoint or tracepoint at these 
points in the program: 

• A breakpoint at a File Description specification occurs before an input or 
update fUe is opened or just before an output file is created. The line number 

of this breakpoint corresponds to the File Description specification for this 
file. 

A breakpoint at an Input specification occurs before the fields are loaded with 
data from a record. The line number of this breakpoint corresponds to the 
record definition in an Input specification. 
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• You can set two breakpoints for each Calculation specification. The first 
breakpoint occurs just after testing control-level indicators, if used, and just 
before testing conditioning indicators. The second breakpoint occurs just 
before executing the operation code. Use the following syntax: 

SET BREAK line-number.statement-number 

For example, assume that a Calculation specification begins with line number 
25. The command SET BREAK 25.1 enables you to test indicators. The 
command SET BREAK 25.2 puts a breakpoint just before the operation code 
is executed. If a Calculation specification has no conditioning indicators, the 
command SET BREAK 25 puts a breakpoint just before the operation code is 

executed. 

You can specify statement numbers only with Calculation specifications that 
have conditioning indicators. 

• A breakpoint at an Output specification occurs after the output buffer has 
been built but before the record is output. The line number of the breakpoint 
corresponds to the record definition in an Output specification. 

E.11.4.2 Setting Breakpoints or Tracepoints on Labels 

You can specify an RPG II label as a breakpoint or a tracepoint. The following 
RPG II labels, which correspond to specific points in the logic cycle, are provide 
in addition to user-defined tags. Note that these labels do not appear in the 
source code but are accessible from the debugger. The labels do appear in the 
machine code listing. 


RPG II Label 

Description and Breakpoint Behavior 

*DETL 

Breaks just before outputting heading and detail lines 

*GETIN 

Breaks just before reading the next record from the primary or 
secondary file 

*TOTC 

Breaks just before performing total-time calculations 

*TOTL 

Breaks just before performing total-time output 

*OFL 

Breaks just before performing overflow output 

*DETC 

Breaks just before performing detail-time calculations 


For example: 

DBG> SET BREAK *TOTL 


E.11.5 


EXAMINE Command 

The EXAMINE command enables you to look at the contents of a variable, the 
current table entry, an array element, or the I/O buffer. 

• To examine an array variable, use array syntax as in the following example: 


DBG> EXAMINE ARR3(9) 
DBG> EXAMINE ARRY(1:7) 


! Display element 9 of array ARR3 
! Display elements 1-7 of array ARRY 


• Specifying a table name enables you to examine the entry retrieved from the 
last LOKUP operation. 
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* uodtffiT the C0 * te f* 0{ the 1/0 buffer, specify the name of the input file 
update file, or output file, followed by the string $BUF. For example the ’ 

INPUT^ C ° mmand displays the contents of the I/O buffer for thehiput file 

DBG> examine input$buf 

Iui1iT"ham”t^ , lo^“ PlayS thC ASC “ equivalent ° f **“ stri ”S STRING, 

DBG> EXAMINE/ASCII:6 STRING 

To examine a variable which contains the at sign (@), use %NAME as follows: 

DBG> EXAMINE %NAME 'ITEMS' 

example^ 116 3 n ° nexternal indicator > precede it with the string *IN. For 

DBG> EXAMINE *IN56 
*IN56: "0" 

Sspkyed^^ ^ S6t ° ff ’ ° iS displayed ‘ If an indicator is set on, 1 is 

You cannot examine external indicators in this manner. To examine external 
in icators, you must first link the program with the /NOSYSSHR LINK 
comman qua lfier; then, use the CALL command, as in the following 
example which displays the value of U5: ® 

DBG> CALL RPG$EXT_INDS(5) 
value returned is 0 

E.11.6 DEPOSIT Command 

Note the following points when using the DEPOSIT command: 

You can deposit a single value into an element of an array using array syntax 
array ARR 0 ^ 6XampIe ’ which deposits the value 150 into dement 2 of 

DBG> DEPOSIT ARR(2) = 150 

’ V ? h “ ,s iDt ° an am V character strings, by using 

qUaMer ^ DEP0SIT l For example, assume 

PARTS is an array of 10 elements in program INVRPG each a chara^ar- 

^ lowing DE^sS 

> » 6 into elements 4, 5, and 6, respectively, of array PARTS - 

nDf\ /,__ J 

"P04P05P06" 


DBG> DEPOSIT/ASCII PARTS(4) 
DBG> EXAMINE PARTS(4:6) 
INV\PARTS 


(4) 

(5) 

( 6 ) 


'P04' 

'P05' 

'P06' 


Values Reposjteoi into n^eric Helds are aligned on the decimal point. Shorter 
fields are padded noth zeros to the left and right of the decimal point. 

Values deposited into character fields are left justified. If the value contains 
^characters than the character field, the field is padded on the ri^t “ ft 
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To set a nonextemal indicator on or off with the DEPOSIT command precede 
the indicator with the string *IN. Depositing the value 1 or 0 sets the 
indicator on or off, respectively. For example, the following command sets 

indicator 56 on: 

DBG> DEPOSIT *IN56 = "1" 


E.11.7 EDIT Command 

The EDIT command invokes the RPG II editor rather than the VAX Language- 
Sensitive Editor. 


E.12 SCAN 

This section describes debugger support for SCAN. 

E.12.1 Operators in Language Expressions 

Supported SCAN operators in language expressions follow: 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 

— 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

& 

Concatenation 

Infix 

= 

Equal to 

Infix 

<> 

Not equal to 

Infix 

> 

Greater than 

Infix 

>= 

Greater than or equal to 

Infix 

< 

Less than 

Infix 

<= 

Less than or equal to 

Prefix 

NOT 

Complement 

Infix 

AND 

Intersection 

Infix 

OR 

Union 

Infix 

XOR 

Exclusive OR 


E12 2 Constructs in Language and Address Expressions 

Supported constructs in language and address expressions for SCAN follow: 


Symbol Con struct _ 

() Subscripting 

Record component selection 
.> Pointer dereferencing 
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E.12.3 Predefined Symbols 

Supported SCAN predefined symbols follow: 

Symbol Meaning "—--- 


TRUE Boolean True 

FALSE Boolean False 


NIL Nil pointer 

Data Types 

Supported SCAN data types follow: 

ouan Data Type 

VAX Data Type Name 

BOOLEAN 

(None) 

INTEGER 

Longword Integer (L) 

POINTER 

(None) 

FIXED STRING (n) 

TEXT with CLASS=S 

VARYING STRING (n) 

TEXT with CLASS=VS 

DYNAMIC STRING 

TEXT with CLASS=D 

TREE 

(None) 

TREEPTR 

(None) 

RECORD 

(None) 

OVERLAY 

(None) 


SET^ ^ n ° Sp6Clfic su PP ort for the following datatypes: FILE, TOKEN, GROUP, 


E.12.5 Names 

E.12.6 
E.12.6.1 


nrnr-T 1 nam6S ° f the followin g SCAN constructs in debugger commands- 

procedures, macros, constants, variables, and labels. gS d 

Controlling Execution 

Note the following points about SCAN breakpoints, traoepoints, and watehpoints. 

Breakpoints and Tracepoints 

You can set breakpoints and tracepoints on procedures, trigger macros syntax 
macros, and labels, m addition to line numbers. For example: ’ Y 


DBG> set BREAK find keyword 

DBG> CANCEL BREAK exit" 

DBG> SET BREAK compare_trees 


break on a trigger macro 
cancel break on label 
break on a procedure 


Conventional breakpoints and tracepoints are not especially convenient for 
monitoring SCAN s picture matching. Where do you set a b “ipoint or 
racepoint to observe the tokens built by your program? There is no statement in 
your program on which to set such a breakpoint. 

lb solve this problem, VAX SCAN defines several events. By setting breakpoints 
or tracepoints on these events, you can observe the picture matchinf process 
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The following event keywords are defined for SCAN programs. 


Event Keyword 

Description 

TOKEN 

A token is built. 

PICTURE 

An operand in a picture is being matched. 

INPUT 

A new line of the input stream is read. 

OUTPUT 

A new line of the output stream is written. 

TRIGGER 

A trigger macro is starting or terminating. 

SYNTAX 

A syntax macro is starting or terminating. 

ERROR 

Picture matching error recovery is starting or terminating. 


Use these keywords with the /EVENT qualifier of the SET BREAK, SET TRACE, 
CANCEL BREAK, and CANCEL TRACE commands. For example, the following 
command sets a breakpoint that triggers whenever a TOKEN is built: 

DBG> SET BREAK/EVENT=TOKEN 

Recognition of SCAN events is enabled automatically by the debugger if the main 
program is written in SCAN. If you are debugging a program written m another 
language that calls a SCAN routine, proceed as follows to set up the SCAM 
environment: 

1 Enter the SET LANGUAGE SCAN command to enable recognition of 
language-dependent operators, expressions, and other constructs. (See t e 
description of the SET LANGUAGE command.) 

2 Enter the SET EVENT_FACILITY SCAN command to enable recognition of 
SCAN events. (See the'description of the SET EVENT.FACILnT ' emmuuKU 
The SHOW EVENT-FACILITY command identifies the current facility ana 

its events. 


E.12.6.2 Watchpoints 

Note the following points about SCAN watchpoints: 

• Variables declared at MODULE level are static by default. 

. Variables declared at PROCEDURE or MACRO level are automatic 


(nonstatic) by default. 

DYNAMIC STRING variables are dynamically built. The storage used to 
hold the value of the string can change when the value of the string changes. 
Thus, the storage the debugger is watching may not be the correct storage if 
the string’s value is changed. 


E.12.7 Examining and Depositing 

The following sections describe how to examine and deposit into the following 
SCAN variables: 

STRING 

FILL 

POINTER 

TREE 

TREEPTR 

RECORD 

OVERLAY 
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E.12.7.1 STRING Variables 

If you deposit into a FIXED STRING variable, truncation will occur if the 
deposited string is longer than the size established by the declaration of that 
variable. 

If you deposit into a VARYING STRING variable, truncation will occur if the 
deposited string is longer than the maximum size established by the declaration 
of that variable. 

If you deposit into a DYNAMIC STRING variable, truncation will occur if the 
deposited string is longer than the current size of the variable. 

With FIXED and DYNAMIC STRING variables, if the deposited string is shorter 
than the current size of the variable, the unfilled portion of the variable will be 
blank padded to the right, with the new string left justified in the variable. 

In the case of VARYING STRING variables, the current size of the variable 
storage space will be adjusted to the size of the deposited string. 

E.12.7.2 FILL Variables 

Examining a FILL variable causes the contents of the specified variable to 
be displayed as a string, by default, and so may have little meaning. If the 
characteristics (or type) of the fill are known, the appropriate qualifier applied to 
the command will produce a more meaningfiil display. The following command 
example shows a fill x that is known to be a single floating number: 

DBG> EXAMINE/FLOAT x 

E.12.7.3 POINTER Variables 

You can examine a POINTER by name to find the address of the variable it points 
to. Use the operator that combines the minus sign and the greater than symbol 
(->) to examine the variable that is based on the POINTER. 

Consider these declarations and assignments: 

TYPE symnode: RECORD 

ptr: POINTER TO symnode, 
vstr: VARYING STRING( 20 ), 

END RECORD; 

DECLARE x : symnode; 

DECLARE xptr: POINTER TO symnode; 
xptr = POINTER(x); 

x.vstr = 'prehensile'; 

The following command displays the value of the vstr component of x : 

DBG> EXAMINE x.vstr 

POINTER\MAINPOINTER\X.VSTR: 'prehensile' 

The following command displays the value of vstr based on the POINTER: 

DBG> EXAMINE xptr->.vstr 
POINTER\MAINPOINTER\XPTR->.VSTR: 'prehensile ' 
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E.12.7.4 TREE and TREEPTR Variables 

You can examine the contents of the nodes in a tree using the following syntax: 

EXAMINE tree_variable([subscript], ... ) 


You cannot deposit into a TREE variable. 

The following declarations and assignments describe a 2-level tree having 
both string and integer subscripts. This data structure is then used in several 
examples which show how to examine TREE and TREEPTR variables. 


MODULE debug_tree; 

DECLARE voters 
DECLARE cityptr 
DECLARE wardptr 


TREE ( STRING, INTEGER) OF INTEGER; 

TREEPTR ( STRING ) TO TREE (INTEGER) OF INTEGER; 
TREEPTR ( INTEGER ) TO INTEGER; 


PROCEDURE debug_exercise MAIN; 
voters ( 'salem', 1 ) = 2500; 
voters ( 'salem', 2 ) = 1500; 
voters ( 'hudson', 1 ) = 3500; 

voters ( 'hudson', 2 ) = 3200; 

voters ( 'hudson', 3 ) = 2900; 

voters ( 'zork', 1 ) = 1000; 

cityptr = TREEPTR ( voters ( 'hudson' ) ); 
wardptr = TREEPTR ( voters ( 'hudson', 2 ) ); 

END PROCEDURE /* debug_exercise */; 

END MODULE /* debug_tree */; 

If you specify the name of a tree with the EXAMINE command, the debugger 
displays the contents of all nodes and leaves of the tree. For examp e. 


DBG> EXAMINE voters 


DEBUG_TREE\VOTERS 

'hudson' 

1: 3500 

2: 3200 

3: 2900 

'salem' 

1: 2500 

2; 1500 

'zork' 

1: 1000 

You can specify an interior node by entering the subscript for that node. For 
example: 

DBG> EXAMINE voters('salem') 


DEBUG TREEWOTERS (' salem') 

“1: 2500 

2; 1500 

You can examine the leaf node in a tree by specifying all subscripts leading to the 
desired leaf. For example: 


DBG> EXAMINE voters ('salem' ,2) 

DEBUG_TREE\VOTERS('salem',2): 1500 

If you examine a TREEPTR variable, such as cityptr or wardptr , the debugger 
displays the address of that tree node. 

The following example shows how to examine what a TREEPTR variable is 
pointing to. 
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DBG> EXAMINE cityptr-> 
DEB(JG_TREE\CITYPTR-> 

1: 3500 

2: 3200 

3: 2900 

DBG> EXAMINE wardptr-> 
DEBUG_TREEDEBUG_TREE\WARDPTR->: 


3200 


E.12.7.5 RECORD and OVERLAY Variables 

of the S fipn EEC0RD ” a “ e ™ th the EXAMINE command, all components 

T>Jrn^ C0RB t ar l P I e f, ented ‘ To examine individual components of the 
KEOORD, specify the full name of each component. 

The general format is as follows: 

EXAMINE recordname 

EXAMINE recordname.componentname.componentname 

You examine an OVERLAY in the same way. All components are again 

STmwrSwl! 3 ’ f 3 I^r-byte i-egion is a FILL(4), an INTEGER, and a VARYING 
biRING(2), the four bytes will be displayed three different ways. 

E.13 Language UNKNOWN 

This section describes debugger support for language UNKNOWN. 

E.13.1 Operators in Language Expressions 

Supported operators in language expressions for language UNKNOWN follow: 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 


Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

~ 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

** 

Exponentiation 

Infix 

& 

Concatenation 

Infix 

// 

Concatenation 

Infix 

= 

Equal to 

Infix 

<> 

Not equal to 

Infix 

/= 

Not equal to 

Infix 

> 

Greater than 

Infix 

>= 

Greater than or equal to 

Infix 

< 

Less than 

Infix 

<= 

Less than or equal to 

Infix 

EQL 

Equal to 

Infix 

NEQ 

Not equal to 

Infix 

GTR 

Greater than 

Infix 

GEQ 

Greater than or equal to 
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Kind Symbol Function 


Infix 

LSS 

Less than 

Infix 

LEQ 

Less than or equal to 

Prefix 

NOT 

Logical NOT 

Infix 

AND 

Logical AND 

Infix 

OR 

Logical OR 

Infix 

XOR 

Exclusive OR 

Infix 

EQV 

Equivalence 


E.13.2 Constructs in Language and Address Expressions 

Supported constructs in language and address expressions for language 
UNKNOWN follow: 

Symbol Construct______ 

[ ] Subscripting 

() Subscripting 

Record component selection 
a Pointer dereferencing 

E.13.3 Predefined Symbols 

Supported predefined symbols for language UNKNOWN follow: 

Sy mbol Meaning ____ 

TRUE Boolean True 

FALSE Boolean False 

NIL Nil pointer 


E.13.4 Data Types „ . .. , . 

When the language is set to UNKNOWN, the debugger understands all data 
types accepted by other languages except a few very language-specific types 
such as picture types and file types. In UNKNOWN language expressions, the 
debugger accepts most scalar VAX Standard data types. 

• For language UNKNOWN, the debugger accepts the dot-notation for record 
component selection. If C is a component of a record B which mtumisa 
component of a record A, C can be referenced as A.B.C . Subscripts can be 
attached to any array components; if B is an array, for instance, C can be 
referenced as “A.B[2,3].C”. 


• For language UNKNOWN, the debugger accepts both round and square 
subscript parentheses. Hence, A[2,3] and A(2,3) are equivalent. 
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A __ 

Abort function, 2-7, 10-9, CD-38, CD-121 

CD-204 

with DECwindows, 1-20 
/ABORT qualifier, CD-178 
/AC 

See /ASCIC qualifier 

/ACTIVATING qualifier, 10-12, CD-17, CD-30 
CD-125, CD-184 
Activation 

predefined tracepoint, multiprocess program 
10-12 

/ACTIVE qualifier, 12-10,12-23, CD-179 

%ACTIVE_TASK, 12-10,12-14 

/AD 

See /ASCID qualifier 
%ADAEXC_NAME, 9-15, D-9 
%ADDR, CD-10 
Address 

depositing into, 4-23 

with DECwindows, 1-25 
examining, 4-13 

with DECwindows, 1-25 
obtaining, 3-12, 4-12 

with DECwindows, 1-24 
specifying breakpoint, 3-11 
symbolizing, 4-13 

with DECwindows, 1-25 
Address expression 
See also Address 
code, 3-10, 4-18, 6-4 

with DECwindows, 1-22 
compared to language expression, 4-7 
with DECwindows, 1-22 
composite, 3-11 
vector, 11-16 

current entity, 4-8, 4-13, D-5 
with DECwindows, 1-9 
DEPOSIT command, 4-3, CD-58 
EVALUATE/ADDRESS command, 3—12 4—12 
CD-79 

EXAMINE command, 4-2, CD-81 
EXAMINE/SOURCE command, 6-4 
logical predecessor, 4-8, 4-13, D-5 
with DECwindows, 1-9 


Address expression (cont’d) 

logical successor, 4-8, 4-13, D-5 
with DECwindows, 1-9 
selecting from DECwindows window, 1-22 
SET BREAK command, 3-8, CD-124 
SET TRACE command, 3—9, CD—183 
SET WATCH command, 3-15, CD-196 
symbolic, 4-4 

with DECwindows, 1-22 
SYMBOLIZE command, 4-13, CD-263 
type of, 4—4 

/ADDRESS qualifier, 8-6, CD-47, CD-79 
CD-243 

/AFTER qualifier, CD-125, CD-184, CD-196 
Aggregate 

DEPOSIT command, 4-16, 4-17 11-6 11-7 
CD-58 

EXAMINE command, 4-16, 4-17,11-6 11-7 
CD-81 

SET WATCH command, 3—17,11-3 
ALLOCATE command 

debugging with two terminals, 9-5 
/ALL qualifier, CD-158 

CANCEL BREAK command, CD—17 
CANCEL DISPLAY command, CD-20 
CANCEL IMAGE command, CD-22 
CANCEL MODULE command, CD—24 
CANCEL TRACE command, CD—30 
CANCEL WATCH command, CD-34 
CANCEL WINDOW command, CD—35 
DELETE command, CD—54 
DELETE/KEY command, CD-56 
EXTRACT command, CD-97 
SEARCH command, CD-115 
SET IMAGE command, CD-138 
SET MODULE command, CD-152 
SET TASK command, CD—179 
SHOW DISPLAY command, CD-212 
SHOW KEY command, CD-218 
SHOW PROCESS command, CD-229 
SHOW TASK command, 12-13,12-19, CD-246 
SHOW WINDOW command, CD-255 
%AP, 4-22, D-3 
Apostrophe (’) 

ASCII string delimiter, 4-15 
instruction delimiter, 4-21 
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/APPEND qualifier, CD-97 
Array type, 4-16 

vector register, 11-6 
/ASCIC qualifier, CD-58, CD-81 
/ASCID qualifier, CD-59, CD-81 
/ASCII qualifier, CD-59, CD—82 
ASCII string type, 4-15, 4-26, CD-58, CD-81, 
CD-191 

/ASCIW qualifier, CD-59, CD-82 
/ASCIZ qualifier, CD-59, CD-82 
AST (asynchronous system trap), 9-16 
CALL command, 9-16, CD—10 
disabling, CD-64 

displaying AST handling conditions, CD-205 
enabling, CD-76 
SHOW CALLS command, 9-16 
AST-driven program 
debugging, 9-16 
Asterisk (*) 

HELP command, CD-102 
multiplication operator, D-7 
/AST qualifier, 9-16, CD-11 
At sign (@) 

contents-of operator, D-7 
execute-procedure command, 8-1, CD-7 
SET ATSIGN command, CD-123 
SHOW ATSIGN command, CD-206 
ATTACH command, 3-4, CD-9 
Attribute ^ 

display, 7-3, 7-6, 7-9, 7-18, CD-117, CD-238 

window 

with DECwindows, 1-10 
AUTO window, DECwindows, 1-11 
/AW 

See /ASCIW qualifier 
/AZ 

See /ASCIZ qualifier 


B___ 

Backslash (\ ) 

current value, 4-6 

global-symbol specifier, 5-10, CD-166, D-7 
path name delimiter, 5—9, 6-4, D-7 
with DECwindows, 1-10, 1-26 
%BIN, 4-11, D-5 

/BINARY qualifier, 4-11, CD-77, CD—79, CD 82 
Bit field operator (<p,s,e>), D-7 
/BOTTOM qualifier, CD-112 
/BRANCH qualifier, CD-17, CD-30, CD-125, 
CD-184, CD-258 
Breakpoint 

canceling, 3-15, CD-17 
defined, 3-8 

delayed triggering of, 3-13, CD-125 
displaying, CD-207 
DO clause, 3-13 


Breakpoint (cont’d) 

exception, 9-10, CD-124 

in tasking (multithread) program, 12—24 

on activation (multiprocess program), 10-12 

on task event, 12—27 

on termination (image exit), 10-12 

on vector instruction, 11-3 

predefined, 9—9 

predefined, tasking (multithread) program, 
12-29 

setting, 3-8, CD—124 
source display at, 6-7 
WHEN clause, 3-13 
with DECwindows, 1-23 
/BRIEF qualifier, CD-218, CD-230 
Built-in symbol, D-2 
/BYTE qualifier, CD-59, CD-82 


c___ 

/CALLABLEJEDT qualifier, CD-134 
/CALLABLE JLSEDIT qualifier, CD-134 
/CALLABLE_TPU qualifier, CD-134 
CALL command, 8-10, CD-10 
and ASTs, 9-16, CD-10 
multiprocess program, 10-5 
vectorized program, 11-22 
with DECwindows, 1-8 
%CALLER_TASK, 12-14 
Call frame 

field and buttons in main window 

with DECwindows, 1-9,1-21,1-26 
/CALL qualifier, CD—17, CD-30, CD-125, 
CD-184, CD-258 

/CALLS qualifier, 12—27, CD—152, CD-246 
Call stack 

See also Scope 

displaying, 2-13, 9-12, CD-209, CD-241 
with DECwindows, 1-23 
used to control instruction display, 7-9, 
CD-166 

with DECwindows, 1-9,1-21 
used to control source display, 7-6, CD-166 
with DECwindows, 1-9,1-21 
used to control symbol search, 5-10, CD-166 
with DECwindows, 1-9,1-26 
CANCEL ALL command, CD-15 
CANCEL BREAK command, 3-15, CD-17 
CANCEL DISPLAY command, 7-12, CD-20 
CANCEL IMAGE command, 5-14, CD-22 
CANCEL MODE command, CD-23 
CANCEL MODULE command, 5-7, CD-24 
CANCEL RADIX command, 4-11, CD-26 
CANCEL SCOPE command, 5-11, CD-27 
CANCEL SOURCE command, 6-3, CD-28 
CANCEL TRACE command, 3-15, CD-30 


Index-2 






CANCEL TYPE/OVERRIDE command, 4—24 
CD—33 

CANCEL WATCH command, 3-15, CD-34 

CANCEL WINDOW command, 7-14, CD-35 

Case sensitivity, 9-9 

Catchall handler, 9-13 

Circumflex ( A ), 4-8, 4-13, D-5 

/CLEAR qualifier, CD-67 

Code 

see Instruction, Address expression 
Colon (:) 

range delimiter, 4-16,11-4,11-6,11-7, CD-81 
Command format 
debugger, CD-3 
Command interface 

COMMAND box, DECwindows, 1—19,1—27 
debugger, 2-1 

with DECwindows, 1-27,1-33 
debugger commands disabled in DECwindows 
1-27 

Command procedure 

See also Initialization file, debugger 
debugger, 8-1 

default directory for, CD-123, CD-206 
displaying commands in, CD-155 
exiting, CD-7, CD-90, CD-106 
invoking, CD-7 
log file as, 8-5 

passing parameters to, 8-2, CD-44 
recreating displays with, 7-21, CD-97 
with DECwindows, 1—28 
/COMMAND qualifier, 8-6, CD-47 
Comment 

format, CD-4 
Compiler 


compiler generated type, 4-4 
/DEBUG qualifier, 5-2, 6-1 
with DECwindows, 1—3 
/LIST qualifier, 6-1 
/NOOPTIMIZE qualifier, 5-2, 9-1 
with DECwindows, 1-3 
Condition handler 
debugging, 9-10 


/CONDITION_VALUE qualifier, CD—77 CD-82 
CONNECT command, 10-4,10-13, CD-36 
Contents-of operator, 4-6,4-19 D -7 

o^ C - INTERCEPTI0N P*ckage, 12-32 
Ctrl/C, 2-7,10-4,10-9, CD-38 
Ctrl/W, CD-40, CD-69 
Ctrl/Y, 2-7, 3-3, 3-4,10-12, CD-41 
interrupting tasks in debugger, 12—32 
with DECwindows, 1-31 
Ctrl/Z, 3-4, CD-40 
%CURDISP, C-6 
%CURLOC, 4-8, 4-13, D-5 
Current 


display, 7-3, 7-18, CD-117, CD-238 


Current (cont’d) 

entity, 4-8, 4-13, 4-19, D-5 
with DECwindows, 1—9 
image, 5-14, CD-138, CD-217 
language, 4-10, CD-141, CD-220 
location, 2-10, 6-4, 6-5, 7-6, 7-9 
with DECwindows, 1-21 
radix, 4-10, CD-164, CD-234 
scope, 5-11, CD-166, CD-235 
type, 4-23, CD-191, CD-252 
value, 4-6, D-5 
Current entity 

field and buttons in main window 
with DECwindows, 1—9 
/CURRENT qualifier, 5-11, CD-166 
%CURRENT_SCOPE_ENTRY D-10 
%CURSCROLL, C-6 
%CURVAL, 4-6, D-5 


D 


See Type 

/DATE_TIME qualifier, CD-59, CD-82 
DBG$DECW$DISPLAY 

with DECwindows, 1-32,1-33 1-34 D-l 
DBG$INIT, 8-4, D-l 
DBG$INPUT, 9-5, D-l 
with DECwindows, 1—33 
DBG$OUTPUT, 9-5, D-l 


with DECwindows, 1-33 
DBG$PROCESS, 2-6,10-1,10-9, D-l 
with DECwindows, 1-3,1-29 
Deadlock 

debugging deadlocks, 12-30 
DEBUG command, 3-3,10-12, CD-41 
with DECwindows, 1-31 
Debugger 

command interface, 2-1 

with DECwindows, 1-27,1-33 
DECwindows interface, 1-1 
displaying command interface on other 
terminal, 9-5 
with DECwindows, 1-33 
displaying DECwindows interface on other 
workstation, 1-32 

invoking from DECwindows File View window, 


invoking over DECnet link, 3-1 
Debugger command 
dictionary, CD-6 
format, CD-3 

repeating, CD-99, CD-109, CD-268 
summary, 2-25 
with DECwindows, 1—27,1—33 
Debugging configuration 
See also Debugger 
default, 2-6,10-9 
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Debugging configuration 
default (cont’d) 

with DECwindows, 1-3 
multiprocess, 10-1,10-9 
with DECwindows, 1-29 
/DEBUG qualifier, 3-1, 5-2, 5-4, 6-1 
shareable image, 5-12 
with DECwindows, 1-3 
Debug symbol table 
See DST 

%DEC, 4-11, D-5 

/DECIMAL qualifier, 4-11, CD-77, CD-79, CD 

DECLARE command, 8-2, CD-44 

DECnet 

debugging over, 3-1 

See Tasking (multithread) program 
DECwindows 

debugger interface, 1-1 
debugging DECwindows application, 
%DECWINDOWS, D-5 
DECwindows interface 
debugger, 1-1 

displaying on other workstation, 1--M 
disabled debugger commands, 1-27 
/DEFAULT qualifier, CD-82 
DEFINE command, 8-6, CD-47 

displaying default qualifiers for, CD-211 
setting default qualifiers for, CD-133 
/DEFINED qualifier, CD-243 
DEFINE/KEY command, 8-8, CD-49 
DEFINE/PROCESS_GROUP command, 10-12, 
CD-52 

DELETE command, 8-6, CD-54 
DELETE/KEY command, 8-8, CD-56 
Deposit 

DEPOSIT command, 4-3, CD-58 
instruction, 4—21,11—12 

with DECwindows, 1-24 
into address, 4—23 

with DECwindows, 1—25 
into register, 4-22,11-4 

with DECwindows, 1-25 
into variable, 4—3, 4—14 

with DECwindows, 1—24 
into vector register, 11-4 
vector instruction, 11-12 
DEPOSIT command, 4-3, CD-58 
%DESCR, CD-10 
/DIRECTORY qualifier, CD-218 
/DIRECT qualifier, CD-243 
DISABLE AST command, 9-16, CD-64 
Display, debugger, screen mode 

See also Source display, Instruction, Window 
attribute, 7-3, 7-18, CD-117, CD-238 
canceling, 7-12, CD-20 
contracting, 7-12, CD-94 


Display, debugger, screen mode (cont d) 

creating, 7-12, CD-65 
current, 7—3, 7—18, CD—117 
default configuration, 7-2, 7-4 
defined, 7-2 
DO display, 7-15,11-23 
expanding, 7—12, CD—94 
extracting, 7—21, CD—97 
hiding, 7-11, CD-67 
identifying, 7 - 12 , CD-212 
instruction display (INST), 7—7, 
kind, 7-3, 7-14, C-l 
list, 7-3, CD-212, C-6 
moving, 7-12, CD-104 
output display (OUT), 7-6, 7-16 
pasteboard, 7—3, CD—70 
predefined, 7-4, C—3 
process specific, 10-14 
prompt display (PROMPT), 7- 
register display (REG), 7-9, 7-17,11 
removing, 7-12, CD-69 
saving, 7-21, CD-110 
scrolling, 7-11, CD-112 
selecting, 7-18, CD-117 
showing, 7-12, CD-65 
window, 7-2, 7-13, C—7 
DISPLAY command, 7-11, 7-12, CD-65 
DO clause 

example, 3-13 
exiting, CD-90, CD-106 
format, CD-4 

DO command, 10-5,10-6, CD-72 
DO display, 7-15, C-l 
/DOWN qualifier, CD-94, CD-104, CD 112 
DST (debug symbol table) 
creating, 5-4 
shareable image, 5-13 
source line correlation, 6-1 
Dynamic mode, CD—148 
image setting, 5-14 
module setting, 5—7 

with DECwindows, 1-26 
Dynamic process setting, 10-7, CD-158 

Dynamic prompt setting, 10_2 ’ lbl 

/DYNAMIC qualifier, CD-67, CD-158, CD 23 
/D_FLOAT qualifier, CD-59, CD-82 


/ECHO qualifier, CD-50 

EDIT command, CD-74 

/EDIT qualifier, CD-28, CD-172, CD-239 

ENABLE AST command, 9-16, CD-76 

/ERROR qualifier, 7-19, CD-117 

Evaluate - Q n * 

%CURVAL built-in symbol, 4-6, CD-78, u o 

expression, 4-3, 4-5, CD-77 
with DECwindows, 1-25 
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Evaluate (cont’d) 

memory address, 4-12, CD-79 
with DECwindows, 1-24 
task, 12-12 

EVALUATE/ADDRESS command, 3-12 3-17 
4-12, CD-79 

EVALUATE command, 4-5, CD-77 
Event 

breakpoint or tracepoint on, 3-14 
tasking (multithread) program, 12—27 
Event facility, 12-27, CD-136, CD-215 
Eventpoint 


See Breakpoint, Tracepoint, Watchpoint 
/EVENT qualifier, 3-14, 12-27, 12-29, CD-17 
CD-30, CD-I 25, CD-I 84 
Examine 


address, 4-23 

with DECwindows, 1—25 
EXAMINE command, 4-2, CD-81 
instruction, 4-19,11-9 

with DECwindows, 1-24 
register, 4-22,11-4 

with DECwindows, 1—25 
task, 12-12,12-26 
using vector mask, 11-13 
variable, 4-2, 4-14 

with DECwindows, 1—24 
vector address expression, 11-16 
vector instruction, 11-9 
vector register, 11-4 
Examine button 

with DECwindows, 1—9 
EXAMINE command, 4-2, CD-81 
EXAMINE/INSTRUCTION command, 4—19, 7 _ 9 j 


EXAMINE/OPERANDS command, 4—19 11-9 
EXAMINE/SOURCE command, 6-4, 7-6 C—4 
Exception 


See also Vector exception 
debugging, 9-10 

Exception breakpoint or tracepoint 
canceling, 9-11, CD-17, CD-30 
qualifying, 9-15, D-9 
resuming execution at, 9-11 
setting, 9-10, CD-125, CD-184 

Exception handler 
debugger as, 3-20 
debugging, 9-10 


/EXCEPTION qualifier, 9-10, CD-17, CD-30 
CD—125, CD-184, CD—258 
Exclamation point (!) 

comment delimiter, CD-4 
log file, 8-5 

%EXC_FACILITY, 9-15, D-9 
%EXC_NAME, 9-15, D-9 
%EXC_NUMBER, 9-15, D-9 


%EXC_SEVERITY, 9-15, D-9 
Execution 

as controlled by debugger, 3—20 
discrepancies caused by debugger, 3—21 
interrupting with Ctrl/C, 2-7 
interrupting with Ctrl/Y, 3-3 
with DECwindows, 1—31 
interrupting with Stop button 
with DECwindows, 1-9,1-20 
monitoring with SHOW CALLS command 
2-13, CD-209 

monitoring with tracepoint, 3-9, CD-183 
with DECwindows, 1—23 
multiprocess program, 10-5, CD-149 
resuming after exception break, 9-11 
starting or resuming with CALL command 
8-10,11-22, CD-10 

starting or resuming with GO command 2-12 
CD-100 

with DECwindows, 1—23 
starting or resuming with STEP command 
3-6, CD-258 
with DECwindows, 1-23 
suspending with breakpoint, 3-8, CD-124 
with DECwindows, 1—23 
suspending with exception breakpoint, 9-10 
CD-125 

suspending with watchpoint, 3-15, 10-15 
CD-196 

with DECwindows, 1-24 
vectorized program, 11-2 
$EXIT, 9-15 

EXIT command, 3-4, 9-15, CD-90 
multiprocess program, 10-8,10-9 
with DECwindows, 1-20 
Exit handler 

debugging, 9-15, CD-90 
executing, 3-4, CD-90 

with DECwindows, 1—20 
execution sequence of, 9-15 
identifying, 9-16, CD-216 
EXITLOOP command, 8-10, CD-93 
/EXIT qualifier, CD—74 
EXPAND command, 7-12, CD-94 
Expression 


-cApjcssiun, ijanguj 

EXTRACT command, 7-21, CD-9 


expression 


F 

Fite " " -- 

See Command procedure, Log file, Initialization 
file, Source file 
Final handler, 9-13 
/FLOAT qualifier, CD-59, CD-82 
/FMASK qualifier, 11-13, CD-84 
















FOR command, 8-9, CD-99 
%FP, 4-22, D-3 

/FULL qualifier, CD—230, CD—246 


G___ 

General register 
See also Register 
/GENERATE qualifier, CD-67 
Global section watchpoint, 10-15 
Global symbol 
See Symbol 
Global symbol table 
See GST 
Go button 

with DEC windows, 1—9 
GO command, 2—12, CD—100 
multiprocess program, 10-5 
with DECwindows, 1—23 
GST (global symbol table) 
creating, 5-4 
shareable image, 5-13 
/G_FLOAT qualifier, CD-59, CD-82 


H 


Handler 

condition, 9—13 
Help 

online, 2-7, CD-102 

for debugger messages, 2-7, CD-o 
with DECwindows, 1-18 
HELP command, 2—7, CD-102 
%HEX, 4-11, D-5 

/HEXADECIMAL qualifier, 4-11, CD-77, CL) /», 
CD-83 

/HIDE qualifier, CD-67 
/HOLD qualifier, 10-3,10-6,12-15, 12 19, 
12-23, CD-158, CD-179, CD-230, CD-247 

Hyphen (-) 

line-continuation character, CD-4: 

/H_FLOAT qualifier, CD-59, CD-83 


I_ _ 

Identifier 

search string, 6-6 

/IDENTIFIER qualifier, 6-6, CD-115 
IF command, 8—9, CD—103 
/IF_STATE qualifier, 8-8, CD-50 
Image 

See also Shareable image 
privileged, securing, 5-5 
shareable, debugging, 5-12 
with DECwindows, 1-28 
Indirection operator 

See Contents-of operator 


Initialization 

debugging session, 3-1, 9-7 
with DECwindows, 1-5 
Initialization code, 9-9 
with DECwindows, 1-5 
Initialization file 

See also Command procedure, debugger 
debugger, 8-4, D-l 

with DECwindows, 1-28 
Input, debugger 

DBG$DECW$DISPLAY 

with DECwindows, 1-32, D-l 
DBG$INPUT, 9-5, D-l 

with DECwindows, 1—33 
/INPUT qualifier, 7-19, CD-117, CD-164, 
CD-256 


Instruction 

See also Vector instruction 
depositing, 4-18, 4-21 

with DECwindows, 1-24 
display (INST), 4-18, 7-7,10-14, C-5 
for routine on call stack, 7 9, CD 1 
with DECwindows, 1-9,1—11,1—21 
display kind, 7-16, C-l 

EXAMINE/INSTRUCTION command, 4-19, 

7—9, C—5 

EXAMINE/OPERANDS command, 4-19 
examining, 4—18, 4—19, 7-7 

with DECwindows, 1-21,1-24 
operand, 4—19, CD—83, CD—150 
optimized code, 7-7, 9-1 

with DECwindows, 1—11,1—21 
selecting from DECwindows window, 1-22 
SET SCOPE/CURRENT command, 7-9, 
CD-166 

window (INST), DECwindows, l" 11 - 
/INSTRUCTION qualifier, 7-9, 7-19, CD 17, 
CD-30, CD-60, CD-83, CD-118, CD-126, 
CD-185, CD-258 
%INST_SCOPE, 7-16,0-5 
Integer type, 4-14, 4—23, 4—25 
I nt erf ace 

See Command interface, DECwindows interface 
Interrupt 

debugging session, 3-4 
execution of command, 2-7, CD-38 
with DECwindows, 1-20 
execution of program, 2-7, 3 - 3 . l°' 5 ’ 10 "^’ 
10-12, CD-36, CD-38, CD-41, CD-149 
with DECwindows, 1-20 
/INTO qualifier, CD-126, CD-185, CD-196, 
CD-258 

^debugger, 2-4, H 3-1,10-1,10-12, CM1 
with DECwindows, 1-2,1-4,1-41 
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J 

/JSB qualifier, 3-12, CD-126, CD-185, CD-258 

K 

Key definition 

creating, 8-8, CD-49 
debugger predefined, B-l 
with DECwindows, 1-29 
debugger predefined, multiprocess, 10-14 
deleting, 8-8, CD-56 
displaying, 8-8, CD-218 

Keypad mode, 8-7, CD-49, CD-149, CD-218 B-l 
Key state, 8-8, CD-49, CD-218, B-l 

L 

%LABEL, 3-10, D-7 

Language 

current, 4-10, CD-141 
identifying, CD-220 
multilanguage program, 9-6 
with DECwindows, 1—28 
setting, 4-10, CD-141 
support by debugger, E-l 
with DECwindows, 1—2 
Language expression 

compared to address expression, 4—7 
with DECwindows, 1-22 
DEPOSIT command, 4-3, CD-58 
EVALUATE command, 4-5, CD-77 
evaluating, 4-5 

with DECwindows, 1-25 
FOR command, 8-9, CD-99 
IF command, 8-9, CD-103 
REPEAT command, 8-10, CD-109 
WHEN clause, 3-13 
WHILE command, 8-10, CD-268 
Language-Sensitive Editor, CD-74 
Last-chance handler, 9-13 
LAT terminal 

debugging using two, 9-6 
/LEFT qualifier, CD-94, CD-104, CD-112 
Lexical function 
See Built-in symbol 
LIB$INITIALIZE, 9-9 
%LINE, D-7 

EXAMINE command, 4—19 
EXAMINE/SOURCE command, 6-4 
GO command, CD-100 
SET BREAK command, 3-10 
SET TRACE command, 3-10 
STEP command, 3-6 
Line mode, CD-149 
Line number 
See also %LINE 


Line number (cont’d) 

selecting from DECwindows window, 1—22 
source display, 6-1, 6-3, 6-4 
with DECwindows, 1-10 
traceback information, 2-13, 5-3 
treated as symbol, 5-9 
/LINE qualifier, 3-12, CD-18, CD-31, CD-83 
CD-127, CD-185, CD-259 
LINK command, 3-1, 5-4, 6-1 
shareable image, 5-12 
with DECwindows, 1—3 
/LIST qualifier, 6-1 

/LOCAL qualifier, 8-6, CD-47, CD-54, CD-243 
Local symbol 
See Symbol 

/LOCK_STATE qualifier, CD-50 
Log file 

as command procedure, 8-5 
debugger, 8-5, CD-155 
with DECwindows, 1—27 
name of, 8-5, CD-143, CD-221 
Logical name 
debugger, D-l 

Logical predecessor, 4-8, 4-13, 4-19, D-5 
with DECwindows, 1-9 
Logical successor, 4-8, 4-13, 4-19, D-5 
with DECwindows, 1—9 
/LOG qualifier, CD-50, CD-56 
/LONGWORD qualifier, CD-60, CD-83 


M 

Margin 

source display, 6-8, CD-144, CD-222 
/MARK_CHANGE qualifier, CD—67 
Mask 


EXAMINE/FMASK command, 11-13 
EXAMINE/TMASK command, 11-13 
masked vector operation, 11-5,11-9,11-13 
register, VMR, 11-5, 11-9, 11-13 
Memory 

effect of debugger, 3-21 
Message 

debugger, 2-7, CD-5 

with DECwindows, 1-20 
MicroVAX 

See Workstation 
Mode 


CANCEL MODE command, CD-23 
SET MODE [NONDYNAMIC command, 5-7 
5-14, CD-148 


SET MODE [NO]INTERRUPT command 
CD-149 


SET MODE [NO]KEYPAD command 8—7 
CD-149 


SET MODE [NOILINE command, CD-149 
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Mode (cont’d) 

SET MODE [NOjOPERANDS command, 4-19, 

CD-150 . _ , 

SET MODE [NO]SCREEN command, 7-1, 

CD-150 

SET MODE [NO]SCROLL command, CD-150 
SET MODE [NOISEPARATE command, 9-5, 
CD-150 

with DECwindows, 1-33 
SET MODE [NO]SYMBOLIC command, 4-15, 
CD-151 

SHOW MODE, CD-224 
/MODIFY qualifier, CD-127, CD-185 
Module, 2-5 

See also Shareable image 
canceling, 5—7, CD-24 
information about, 5-7, CD-225 
setting, 5—6, CD—152 

with DECwindows, 1—26 
traceback information, 5-3 
with DECwindows, 1-3 
/MODULE qualifier, CD-28, CD-167, CD-172 
MOVE command, 7—12, CD-104 
Multilanguage program 
debugging, 9-6 

with. DECwindows, 1—28 
Multiprocess program 

CALL command, CD-10 
CONNECT command, 10-4,10-13, CD-3b 
controlling execution, 10-5 
DBG$PROCESS, 10-9 
debugging, 10-1 

with DECwindows, 1-9,1-29 
DEFINE/PROCESS_GROUP command, CD-52 
DO command, 10-5, CD-72 
EXIT command, 10-8,10-9, CD-90 
with DECwindows, 1—20 
global section watchpoint, 10—15 
GO command, 10-5, CD—100 
QUIT command, 10-8,10-9, CD-106 
with DECwindows, 1-20 
screen mode features, 10-14 
SET MODE [NOIINTERRUPT command, 

10-6, CD-149 

SET PROCESS command, 10-6,10-7, CD 15 / 
SHOW PROCESS command, 10-2, CD-229 
specifying processes, 10-11 
STEP command, 10-5, CD-258 
system requirements, 10—16 
with DECwindows, 1—9,1—29 
Multithread program 

See Tasking (multithread) program 


N _ 

%NAME, D-4 
Network 

debugging over, 3-1 
%NEXTDISP, C-6 
%NEXTINST, C-6 
%NEXTLOC, 4-8, 4-13, D-5 
Next location 

See Logical successor 
%NEXTOUTPUT, C-6 
/NEXT qualifier, 6-6, CD-115 
%NEXTSCROLL, C-6 
%NEXTSOURCE, C-6 
%NEXT_PROCESS, 10-11 
%NEXT_SCOPE_ENTRY, D-10 
%NEXT_TASK, 12-14 
Nonstatic variable, 3-17, 4-1 
with DECwindows, 1-24 
/NOOPTIMIZE qualifier, 2-5, 5-2, 9-1 
with DECwindows, 1-3 
NOP (No Operation) instruction, 4-21 


Object module, 5-3, 6-1 

JSSw. JStef 4-11. CD-77, CD-79, CD-83 
/OCTAWORD qualifier, CD-60, CD-83 
Operand 

instruction, 4—19, CD-83, CD—150 
vector instruction, 11-5,11-9 
/OPERANDS qualifier, 4-19, 11-9, CD-83, 
CD-150 
Operator 

address expression, D-6 
language expression, E-l 
Optimization 

effect on debugging, 2-5, 5-2, 7-7, 9 i 
with DECwindows, 1-3,1-10,1-11 
/OPTIMIZE qualifier, 2-5, 5-2, 9-1 
with DECwindows, 1-3 
/OPTIONS qualifier, 5-12 

configuration, displaying, 8-2, 8-5, < C1 ^I 228 
configuration, setting, 8-2, 8-5, CD-155 
debugger, DBG$DECW$DISPLAY 
with DECwindows, 1—32, D—1 
debugger, DBG$OUTPUT, 9—5, D—1 
with DECwindows, 1—33 
display (OUT), 7-6, C—4 

with DECwindows, 1—10 
display kind, 7-16, C-l 

window (OUT), DECwindows, 1-10 

/OUTPUT qualifier, 7-19, CD-118, CD 164, 
CD-256 
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/0V ^ qUalifier> CD -127, CD-186, CD-197 
CD-259 

/0 VERR IDE qualifier, 4-24, CD-26, CD-33 
CD-164, CD-192, CD-234, CD-252 
Override type, 4-24 


/PACKED qualifier, CD-60, CD-84 

%PAGE, C-6 

/PAGE qualifier, 7-22, CD-181 
Parameter 

%pSSNT, r 8-^0^ Pr ° Cedure ’ 8-2,00-44 
Pasteboard, 7-3 
Path name 

abbreviating, 5-9 
numeric, 5-10 
relation to symbol, 5-9 
with DECwindows, 1-10 
syntax, 5-9 

to specify scope, 3-11,5-8,5-9 
with DECwindows, 1-26 

%PC 
See PC 

PC (program counter) 

built-in symbol (%PC), 4-22, D-3 
content of, 2-11,4-19 

EXAMINE/INSTRUCTION command, 7-9, 
7—16 

EXAMINE/OPERANDS command 4—19 11—9 
EXAMINE/SOURCE command, 6-4, 7-6, 7-13 
7—20 5 

examining, 4-19,11-9 
with DECwindows, 1-24 
scope, 5-8 

SHOW CALLS display, 2-13, CD-209 
Penod (.) 

contents-of operator, 4-6, 4-19, D-7 
current entity, 4-8, 4-13, D-5 ’ 

Pointer type, 4-18 

/POP qualifier, CD-67, CD-162 

Pop-up menu 

with DECwindows, 1-12 
Predecessor 

See Logical predecessor 

CD - 15 ’ CD - I 8.CIW1, 

Previous location 

See Logical predecessor 
%PREVIOUS_PROCESS 10-11 
%PREVIOUS_SCOPE ENTRY D-10 
%PREVIOUS_TASK, "12-14 ’ 

%PREVLOC, 4-8, 4-13, D-5 
Primary handler, 3-20, 9-13 
Priority 

of task or thread, 12-15, 1 2-19 


/PRIORITY qualifier, CD-179, CD-247 
Privilege 

allocate terminal, 9-6 
Process 


;-jjicucmieu, iu—Iz 

connecting debugger to, 10 - 4 , 10-13, CD-36 
multiprocess debugging, 10—1 
with DECwindows, 1—9,1—29 
/ DD^ natl ° n tracepoint, predefined, 10-12 
/-PROCESS qualifier, 10-5,10-14 CD-68 rn _79 
/PROCESS_GROUP qualifier, 10-12 CD-52 
%PROCESS_NAME, 10-11 
%PROCESS_NUMBER, 10-11 
%PROCESS_PID, 10-11 
Program 

display kind, 7-18, C-l 
Program counter 


See PC 

/PROGRAM qualifier, 7-19, CD-118 
Prompt 

COMMAND box, DECwindows 1—27 
debugger (DBG>), 2-6,10-2, CD-161 
with DECwindows, 1-27,1-33 
display (PROMPT), 7-7, C-4 
multiprocess program, 10-2 
/PROMPT qualifier, 7-20, CD-118 
Protection 

debugging with two terminals, 9-6 
of terminal, 9-6 
%PSL, 4-22, D-3 

PSL (processor status longword), 4—22 
/PSL qualifier, CD-84 
/PSW qualifier, CD-84 
/PUSH qualifier, CD-69 


Q 

—ORD quafifier, 11-6, n_ 7> CD-60, 

QUIT command, 3-4, CD-106 
multiprocess program, 10-8,10-9 
with DECwindows, 1-20 

Quotation mark (") 

ASCII string delimiter, 4-15 
instruction delimiter, 4—21 


R_ 

Radix 

canceling, CD-26 
conversion, 4-10, D-5 
current, 4-10, CD-164 
displaying, CD-234 
multilanguage program, 9-8 
specifying, 4-10, CD-164 
Range 

colon (:), 4-16,11-4,11-6, H_ 7 , CD-81 
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Real type, 4-14 
Record 

source line correlation, 6-1 
Record type, 4-17 
%REF, CD-10 
/REFRESH qualifier, CD-69 
Register 

See also Vector register 
built-in symbol, 4-22, D-3 
depositing into, 4-22 

with DECwindows, 1-25 
display (REG), 7—9, C—5 

with DECwindows, 1-12 
display kind, 7-17, C-l 
examining, 4-22 

with DECwindows, 1-25 


PC 

See PC 


PSL, 4-22 
symbol, D-3 

symbolizing, 4-13, CD-263 
with DECwindows, 1-25 
variable, 3-17, 4-1 

with DECwindows, 1—24 
watchpoint, 3-17 _ 

window (REG), DECwindows, 1-1 
/RELATED qualifier, CD-24, CD-152, CD 225 
/REMOVE qualifier, CD-69 
REPEAT command, 8-10, CD-109 
/RESTORE qualifier, CD-179 
Return key 

logical successor, 4-8, 4-13,1*-° 

/RETURN qualifier, CD-127, CD-1 ® 6 ’ C1 ? 259 
/RIGHT qualifier, CD-94, CD-104, CD 112 


Routine 

rallinff 8-10,11-22, CD-10 
call stack, 2-13, 7-6, 7-9, CD-166 CD-209 
with DECwindows, 1-21,1-23,1-26 
displaying instructions for, on call stack, 7-9, 
CD-166 

with DECwindows, 1-21 
displaying source code for, on call stack, 7-6, 
r>r>_i 


with DECwindows, 1—21 

EXAMINE/SOURCE command, 6-4 
multiple invocations of, 5-10, CD-166 
with DECwindows, 1-26 
selecting from DECwindows window, 1-22 
SET BREAK command, 3-10 
SET SCOPE command, CD-166 
SET TRACE command, 3-10 
SHOW CALLS command, 2-13 
traceback information, 5-3 
with DECwindows, 1—23 
RST (run-time symbol table), 5-6 
and symbol search, 5-8 
deleting symbol records in, 5-7, DD ^ 


RST (run-time symbol table) (cont’d) 
displaying modules in, 5-7, CD-225 
a;=r.iaiHncr svmbols in, 5-9, CD-243 


shareable image, 5-13 
with DECwindows, 1-26 
RUN command, 3—1, 3—3, 5—4 
See also Execution 
shareable image, 5-13 
with DECwindows, 1—4 
Run-time symbol table 


See RST 


SAVE command, 7-21, CD-110 

/SAVE_VECTOR_STATE qualifier, 11-22, CD li 

Scalar type, 4-14 

SC °biilt-in symbol, 7-4, 7-7, 7-16, 7-18, C-3, 
C-5, D-10 

canceling, 5—11, CD—27 
current, 5—11, CD—166 
default, 5-8, CD-27, CD-167, CD-235 
with DECwindows, 1-26 
displaying, 5-11, CD-235 
for instruction display, 7-9, CD-166 
with DECwindows, 1-9,1-21 
for source display, 7-6, CD-166 
with DECwindows, 1-9,1-21 
for symbol search, 3-11, 5-8, 5-11, CD-2 , 
CD-166, CD-235 


PC 5—8 

relation to call stack, 5—10, 5—11, 7—6, 7 9, 
CD- 166 

with DECwindows, 1-9,1-21,1-26 
SEARCH command, 6-6, CD-114 
search list, 5-8, 5-11, CD-27, CD-166, 
CD-235 

with DECwindows, 1-9,1-26 


CD-166 

setting, 5—11, CD-166 

with DECwindows, 1-26 
specifying with path name, 5-9 
TYPE command, 6-4, CD-266 
vector register, 11—1 


Screen display 

See Display, debugger, screen mode 

Screen management 

debugging DECwindows application, l-M 
debugging screen-oriented program, 9—5 
with DECwindows, 1-33 
Screen mode, 7—1, CD—150 

multiprocess program, 10-14 
summary reference information, C-l 
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Screen-oriented program 
debugging, 9-5 

with DECwindows, 1-32,1—33 
Screen size 

displaying, 7-22, CD-249 
%PAGE, % WIDTH symbols, C -6 
setting, 7-22, CD-181 
/SCREEN_LAYOUT qualifier, CD —97 
SCROLL command, 7-11, CD -112 
Scroll mode, CD-150 
/SCROLL qualifier, 7-20, CD-118 
SEARCH command, 6 - 6 , CD-114 

displaying default qualifiers for, 6-7, CD-237 
setting default qualifiers for, 6 - 7 , CD-170 
Search list 

scope, 5-8, 5-11, CD-166, CD-235 
with DECwindows, 1-9,1-26 
source file, &- 2 , CD-28, CD-172, CD-239 
Security 
image, 5-5 
terminal, 9-6 

SELECT command, 7-18, CD-117 
Semicolon (;) 

command separator, CD -4 
SET ABORT_KEY command, 2—7 CD —121 
SET ATSIGN command, 8 - 2 , CD-123 
SET BREAK command, 3-8, 6-7 9-10 11-3 
12-24,12-27, CD-124 
SET DEFINE command, 8 - 6 , CD-133 
SET EDITOR command, CD-134 
SET EVENT_FACILITY command, 12—28 
CD—>136 

SET IMAGE command, 5-14, CD-138 
effect on symbol definitions, CD-48 
SET KEY command, 8 - 9 , CD-140 
SET LANGUAGE command, 4-10 CD -141 
SET LOG command, 8 - 5 , CD-I 43 ’ 

SET MARGINS command, 6 - 8 , CD-144 
SET MAX_SOURCE_FILES command 6—3 
CD-147 

SET MODE command, CD-148 

SET C D-? 48 [N0]DYNAMIC command, 5-7, 5-14, 

® [NO]G_FLOAT command, CD-148 

SET MODE [NOJINTERRUPT command, 10-5 
CD-149 

SET MODE [NOJKEYPAD command 8-7 
CD-149, B-l 

SET MODE [NOJLINE command, CD —149 
SET MODE [NOjOPERANDS command, 4-19, 

CD—150 

SET MODE [NOJSCREEN command 7-1 
CD-150 

[NOJSCROLL command, CD-150 
SET MODE [NOJSEPARATE command, 9 - 5 , 

CD—150 

with DECwindows, 1—33 


SET MODE [NOJSYMBOLIC command, 4-13 
CD—151 

SET MODULE command, 5-6,5-15 CD -152 
SET OUTPUT command, CD-155 
SET OUTPUT [NO]LOG command, 8 - 5 , CD-155 
SET OUTPUT [NO]SCREEN_LOG command 
8-5, CD-155 

SET OUTPUT [NOJTERMINAL command, 

CD—155 

SET OUTPUT [NOJVERIFY command, 8—2 
CD—155 

SET PROCESS command, 10-6, 10-7 CD-157 
SET PROMPT command, CD-161 
SET RADIX command, 4-10, 9 - 8 , CD-164 
SET SCOPE command, 5 - 11 , 6-4 7-6 7-9 
CD-166 ’ 

SET SEARCH command, 6-7, CD-170 
SET SOURCE command, 6 - 2 , CD-172 
SET STEP command, 3-7, 4-18, 6-7 11-3 
CD—17 5 

SET TASK command, 12-10,12-22 CD-178 
SET TERMINAL command, 7-22, CD-181 
SET TRACE command, 3-9, 6 - 7 , 9-10 11-3 
12-24,12-27, CD-183 
SET TYPE command, 4-23, CD-191 
SET TYPE/OVERRIDE command, 4-24 CD -191 
SET VECTOR_MODE command, 11 - 19 , CD -194 

SET W?NDOW° mmand ’/' 15 ’ 6 ~ ?> 11_3 ’ C °- 196 
SET WINDOW command, 7-14, CD-202 

/SET_STATE qualifier, 8 - 9 , CD-50 

Shareable image 

See also Module 

CANCEL IMAGE command, 5-14, CD -22 
debugging, 5-12 

with DECwindows, 1-28 
SET BREAK/INTO command, 3-12 CD-128 
SET IMAGE command, 5-14, CD-138 
SET STEP INTO command, 3-8, CD-176 
SET TRACE/INTO command, 3-12 CD-186 
SET WATCH command, 3-20 J 
SHOW IMAGE command, 5-13 CD-217 
STEP/INTO command, CD-259 
/SHAREABLE qualifier, 5-12 

/SHARE qualifier, 3-12, 5-15, CD-128, CD-186 
CD-225, CD-259 ’ 

SHOW ABORT_KEY command, CD-204 
SHOW AST command, 9-16, CD-205 
SHOW ATSIGN command, 8 - 2 , CD-206 
SHOW BREAK command, 3 - 9 , CD-207 
SHOW CALLS command, 2-13, 3 - 3 , 9-10 9-16 
CD-209 ’ ’ 

SHOW DEFINE command, 8 - 6 , CD -211 
SHOW DISPLAY command, 7-12 CD-212 
SHOW EDITOR command, CD-214 
SHOW EVENT_FACILITY command, 3-14 
12-28, CD-215 


Index-11 














SHOW EXIT_HANDLERS command, 9-16, 

CD-216 

SHOW IMAGE command, 5-13, CD-217 
SHOW KEY command, 8-8, CD-218 
SHOW LANGUAGE command, 4-10, CU-ZZU 
SHOW LOG command, 8-5, CD-221 
SHOW MARGINS command, 6-8, CD-222 
SHOW MAX_SOURCE_FILES command, 6-3, 
CD-223 

SHOW MODE command, CD-224 rn _ 99 , 

SHOW MODULE command, 5-7,5-15, CD-225 
SHOW OUTPUT command, 8-2, 8-5, CD 228 
SHOW PROCESS command, 10-2,11-2, CD 2zy 
SHOW RADIX command, 4—10, CD-234 
SHOW SCOPE command, 5-11, CD-235 
SHOW SEARCH command, 6-7, CD-237 
SHOW SELECT command, 7-20, CD-238 
SHOW SOURCE command, 6-2, CD-239 
SHOW STACK command, 9-12, CD-241 
SHOW STEP command, 3-7, CD-242 
SHOW SYMBOL command, 5-9,12-26, CD-243 
SHOW SYMBOL/DEFINED command, 8-6 
SHOW TASK command, 12-13,12-15, CD-2 
SHOW TERMINAL command, 7-22, CD-249 
SHOW TRACE command, 3-9, CD-250 
SHOW TYPE command, 4—24, CD-252 
SHOW VECTOR_MODE command, 11-19, 
CD- 253 

SHOW WATCH command, 3-15, CD-254 
SHOW WINDOW command, 7-14, CD-255 
/SILENT qualifier, 3-13,12-31, CD-128, CD- , 
CD-197, CD-259 
/SIZE qualifier, CD-69 
Slash(/) 

division operator, D-7 
SMG$ 

debugging screen-oriented program, 9-5 
/SOURCE, 12-26 
Source code 

See Source display 
Source directory 

displaying, 6-2, CD-239 
search list, 6-2, CD—28, CD—172 
Source display, 2—8, 6-1, 7—1 
discrepancies in, 7—4, 9—1 
with DECwindows, 1-10 
display kind, 7-17, C-l 
EXAMINE/SOURCE command, 6-4, /-b, / 
C-4 

for routine on call stack, 7-6, CD-166 
with DECwindows, 1-9,1-10,1-21 
line-oriented, 6-3 
margins in, 6-8, CD-222 

multiprocess program, 10-14 

not available, 2-10, 2-11, 6-1, 7-4, CD-172, 
C-4 

with DECwindows, 1-10,1-21 
optimized code, 2-5, 5-2, 7—7, 9-1 


Source display 

optimized code (cont d) 

with DECwindows, 1-10 
SEARCH command, 6-6, CD-114 
SET BREAK command, 6-7 
SET SCOPE/CURRENT command, 7-6, 

CD-166 

SET STEP command, 6-7, CD-175 
SET TRACE command, 6-7 
SET WATCH command, 6-7 
SRC, predefined, 7-4, C-3 
with DECwindows, 1-10 
STEP command, 6-7 
TYPE command, 6-3, CD-266 
with DECwindows, 1—9,1-10,1—21 
Source file 

See also Source display 

correct version of, CD-172, CD-239 

defined, 6—2 

file specification, 6-2 

location, 6-2, CD-28, CD-172, CD-239 

maximum number, 6-3, CD-147, CD 223 

not available, 6-2, CD—172 

Source line correlation, 6-1 a* 

/SOURCE qualifier, 6-4, 6-7, 7-6, 7-20, CD 8 , 
CD-118, CD-128, CD-187, CD-197, CD 260 

Source window 

See also Source display 
SRC, DECwindows, 1-10,1-21 
%SOURCE_SCOPE, 7-18, C-3 
%SP, 4-22, D-3 
SPAWN command, 3-4, CD-256 

SRC a n-A C 3 

source display, screen mode, 7-4, C-o 

source window, DECwindows, 1-10,1-21 
SS$_DEBUG condition, D-l 
Stack 

See also Call stack, Call frame, Scope 
variable, 3—17,4—1 

with DECwindows, 1-24 
/START.POSITION qualifier, CD-134 
State 

of task or thread, 12-15,12-19 
/STATE qualifier, 8-8, CD-57, CD-140, CD-2 , 
CD-247 

/STATIC qualifier, CD-197 
Static variable, 3-17, 4-1 
/STATISTICS qualifier, CD-247 
Step button 

with DECwindows, 1-9 
STEP command, 3-6, 6-7, CD-258 

and instruction-level debugging, 4—18 

displaying default qualifiers for, CD-242 
multiprocess program, 10-5 
setting default qualifiers for, CD-175 
vectorized program, 11-3 
with DECwindows, 1-23 
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Stop button 

with DEC windows, 1-9,1-20 
STOP command, 3-4 
/STRING qualifier, 6-6, CD-115 
String type, 4-15, 4-26 


Successor 

See Logical successor 

/SUFFIX qualifier, 10-14, CD-20, CD-69 CD-94 
CD-97, CD-104, CD-110, CD-112, CD-119 
CD-161, CD-212 
Symbol 


See also DST, GST, RST, Scope 
ambiguity, resolving, 5—7 
with DECwindows, 1—26 
built-in, C—5, D-2 
compiler generated type, 4—4 
defining, 8-6, CD-48 
displaying, 5-9, 8-6, CD-48, CD-243 
with DECwindows, 1-24 
global, 5-4,5-10 
image setting, 5-14 
label, 3-10, 5-1 
line number, 3-11, 5-1 
local, 5-4 
module setting, 5—6 

with DECwindows, 1—26 
not in symbol table, 5-6, 5-15 
with DECwindows, 1—26 
not unique, 5-9 

with DECwindows, 1-26 
overloaded, 12-26, E-4, E-17 
relation to address expression, 4- 4 
with DECwindows, 1—22 
relation to path name, 5—9 
with DECwindows, 1-10 
routine, 3-10, 5-1 

search based on call stack, 5-11, CD-166 
with DECwindows, 1—9,1—26 
search conventions, 3-11, 5-8, CD-167 
with DECwindows, 1-9,1-26 
SET SCOPE command, 5-11, CD-166 
shareable image, 5-13 

with DECwindows, 1—28 
show symbol 

with DECwindows, 1-24 
SHOW SYMBOL command, 5-9 
symbolic mode, 4-13, CD-151 
traceback information, 5-3 
universal, 5-4,5-5,5-12,5-15 
variable, 3-15,4-1,4-14,5-1 
vector register, 11-1 
Symbolic mode, 4-13, CD-151 
/SYMBOLIC qualifier, 4-13, CD-84 
Symbolize 

address, 3-12, 4-13, CD-263 
with DECwindows, 1-25 
register, 4-13, CD-263 


Symbolize 

register (cont’d) 

with DECwindows, 1—25 
vector register, 11-1 

SYMBOLIZE command, 3-12, 4-13, CD-263 
Symbol record 
See Symbol 
Symbol table 

See DST, GST, RST 
Synchronization 

debugging vectorized program, 11-19, CD-194 
CD—253, CD—264 

delivery of vector exception, 11-19,11-22 
SET VECTOR_MODE command 11—19 
CD-194 

SHOW VECTOR_MODE command 11—19 
CD-253 

SYNCHRONIZE VECTOR.MODE command 
11-19, CD-264 

/SYSTEM qualifier, 3-12, CD-128, CD-187 
CD-260 
System space 

SET BREAK command, CD-128 
SET STEP command, CD-176 
SET TRACE command, CD-187 
STEP command, CD-260 


T 


Task, 12-1 


See also Tasking (multithread) program 
%TASK 
See Task ID 

Task ID, 12-6,12-12,12-14,12-15,12-19 
Tasking (multithread) program 
active task, 12-10 
comparison of task and DECthreads 
terminology, 12-2 

controlling and monitoring execution, 12-24 
controlling task switching, 12-23 
deadlock condition, 12-30 
debugging, 12-1 

with DECwindows, 1-28 
environment task, 12-6 
event facility, 12-27 
eventpoints, 12-24 
monitoring events, 12-27 
null task, 12-13 

obtaining information about, 12-15 
obtaining priority of task or thread 12-15 

io in ’ , 


sample Ada program for debugging, 12-6 
sample C program for debugging, 12-2 
SET EVENT_FACILITY command, 12—28 
CD—136 } 

SET TASK command, 12-22, CD-178 
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Tasking (multithread) program (cont’d) 

setting breakpoint, 12-24 19 99 12 30 

setting priority of task or thread, 12-22,JU 
setting time-slice value, 12-23 
setting tracepoint, 12-24 

setting watchpoint, 12-24 a 

SHOW EVENT_FACILITY command, 12-2X, 

CD- 215 

SHOW TASK command, 12-15, CD-246 
specifying task body, 12-12 
specifying tasks or threads, 12-10 
stack checking, 12-31 
state of task or thread, 12-15,12-19 
substate of task or thread, 12-15,12-19 
task built-in symbols, 12-13 
task event, 12—27 

task ID, 12-6,12-12,12-14,12-15,12-19 
task object, 12-11 
visible task, 12—10 

/TASK qualifier, 12-12, CD-60, CD-84 
Task state, 12—15,12—19 
Task substate, 12-15,12-19 
Task switching, 12-9,12-23,12-26 
$TASK_BODY, 12-12,12-25 
/TEMPORARY quabfier, CD-128, CD-IS C 

CD-197 

Terminal 

for debugger input/output, separate, 9 o, 
CD-150 

using DECterm window, 1-33 

Terminal emulator 
See also Terminal 
Terminal screen size 
See Screen size 

/TERMINATE qualifier, 8-8, CD-50 
/TERMINATING qualifier, 10 - 12 , CD-18, CD 31, 
CD-129, CD-187 
Termination 

debugging session, 3-4,10-8, CD-90, CD 10 
with DECwindows, 1—20 
execution of handlers at, 9-15 
multiprocess program, 10-8,10-9,10 12 

Thread 

See Tasking (multithread) program 

/TIME_SLICE qualifier, 12-23, CD-179, CD 247 
/TMASK qualifier, 11-13, CD-84 
/TOP quabfier, CD—113 
Traceback 

compiler option, 5—3 
link option, 5-4 
SHOW CALLS display, 2-13 
/TRACEBACK qualifier, 3-3, 5-4, 5-5 
shareable image, 5-13 
Tracepoint 

canceling, 3-15, CD-30 
defined, 3-9 

delayed triggering of, 3-13, CD-184 
displaying, CD-250 


Tracepoint (cont’d) 

DO clause, 3-13 

exception, 9-10, CD-183 OA 

in tasking (multithread) program, 12-^4 
on activation (multiprocess program), 10 
on task event, 12-27 
on termination (image exit), 10—12 
on vector instruction, 11-3 
predefined, 10—12 
setting, 3-9, CD-183 
source display at, 6-7 
WHEN clause, 3-13 
with DECwindows, 1-23 
Transfer address, 3-1, 9-7 
Type 

address expression, 4-4, 4-23 
array, 4-16 

ASCII string, 4-15, 4-26 
compiler generated, 4-4, 4-14 
conversion, numeric, 4-7 
current, 4-23, CD-191, CD-252 
displaying, CD-252 
integer, 4-14, 4-25 
override, 4-24, CD—191 
pointer, 4—18 
real, 4-14 
record, 4-17 
scalar, 4-14 

SET TYPE command, 4-23, CD-iyi 
symbolic address expression, 4-4 
/TYPE qualifier, 4-26, CD-60, CD-85, CD-243 
VAX instruction, 4-18 
vector register, 11-6 
TYPE command, 6-3, 7-6, CD-266 
Type override, 4-24, CD-33,“ 9A o 




u 


Universal symbol 
See Symbol 

/UP qualifier, CD-95, CD-105, CD-113 
/USER quabfier, CD-15, CD-18, CD-31, CD 207, 
CD-250 


V __ 

%VAL, CD-10 

/VALUE quabfier, 8-6, CD-47 
Variable 

as override type, 4-26 
depositing into, 4-3, 4-14 
with DECwindows, 1-24 
examining, 4-2, 4-14 

with DECwindows, 1-24 
global section, 10-15 
initialized, 4—1 
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Variable (cont’d) 

nonstatic, 3-17,4-1 

with DEC windows, 1—24 
optimized code, 9-1 
register, 3-17,4-1 

with DECwindows, 1—24 
selecting from DECwindows window 1—22 
stack local, 3-17,4-1 

with DECwindows, 1—24 
static, 3-17 
uninitialized, 3-21 
watchpoint, 3-15,10-15 
with DECwindows, 1-24 
Variable name 

address expression, 4-7 
with DECwindows, 1-22 
DEPOSIT command, 4—3 
EXAMINE command, 4—2 
language expression, 4-6 
selecting from DECwindows window 1-22 
SET WATCH command, 3-15 
VAX Language-Sensitive Editor, CD -74 
VAXstation 

See Workstation 

VAX Vector Instruction Emulation Facility 
See WIEF 
%VCR 
See VCR 

VCR (vector count register), 11-4, D-3 
Vector count register 
See VCR 
Vector exception 

delivery of, 11-19,11-22 

Vector instruction, 11-8 
CANCEL BREAK/VECTOR_INSTRUCTION 

command, 11-3, CD-18 
CANCEL TRACE/VECTORJNSTRUCTION 
command, 11-3, CD-31 
delivery of vector exception, 11-19,11-22 
depositing, 11-12 
displaying, 11-8 

EXAMINE/OPERANDS command, 11—9 

examining, 11-9 
masked operation, 11-9, 11-14 
operand, 11-9 
replacing, 11-12 

SET BREAK/VECTOR.INSTRUCTION 

command, 11-3, CD-129 
SCT STEP TOCTORJNSTEUCHON command, 
11-3, CD-176 

SET TRACE/VECTOR.INSTRUCTION 

command, 11-3, CD-187 
STEP/VECTOR_INSTRUCTION command 

11-3, CD-260 
Vectorized program 

CALL/[NO]SAVE_VECTOR_STATE command 

11-22, CD-11 


Vectorized program (cont’d) 

controlling and monitoring execution, 11-2 
debugging, 11-1 

with DECwindows, 1-29 
delivery of vector exception, 11-19,11-22 
depositing into vector register, 11—4,11—6 
depositing vector instruction, 11-12 
EXAMINE/FMASK command, 11—13 
EXAMINE/OPERANDS command 11-9 
CD-83 

EXAMINE/TMASK command, 11-13 
examining vector instruction, 11-9 
examining vector register, 11—4,11—6 
masked operation, 11-5,11-9, 11-13 
obtaining information about, 11-2 
setting breakpoint, 11-3 
setting tracepoint, 11-3 
setting watchpoint, 11-3 
SET VECTOR.MODE command, 11-19 
CD-194 

SHOW PROCESS/FULL command, 11—2 
SHOW VECTOR_MODE command, 11-19 
CD-253 

specifying vector register, 11-4 
SYNCHRONIZE VECTOR_MODE command 
11-19, CD-264 

synchronizing scalar and vector processors, 
11—19 

VO to V15, 11-6 
VCR, 11-4 
VLR, 11-4 

VMR, 11-5,11-9,11-13 
with DECwindows, 1-29 
Vector length register 
See VLR 

Vector mask register 
See VMR 
Vector mode 

SET VECTOR.MODE [NOJSYNCHRONIZED 
command, 11-19 

SYNCHRONIZE VECTOR.MODE command, 
11—19 

Vector register 
See also Register 
built-in symbol, 11-4, D-3 
composite address expression, 11—16 
depositing into, 11-4,11-6 
display, screen mode, 7-9, 7-15, 11-23 
examining, 11-4,11-6 
scope, 11-1 
VO to VI 5, 11-6, D-3 
VCR, 11-4, D-3 
VLR, 11-4, D-3 
VMR, 11-5,11-9,11-13, D-3 
watchpoint, 11-3 
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/VECTOR.INSTRUCTION qualifier U-J, 

CD-18, CD-31, CD-129, CD-187, CD-260 

Vei SET OUTPUT VERIFY command, CD-155 

Virtual memory address 
See Memory address 

Visible process, 10—2,10—7 

field and buttons in main window 
with DECwindows, 1—9 

/VISIBLE qualifier, 12-11, CD-158, CD-17 , 
CD—230 

%VTSIBLE_PROCESS, 10-11 

%VISIBLE_TASK, 12-10,12-14 

%VLR 
See VLR 

VLR (vector length register), 

%VMR 
See VMR 

VMR (vector mask register), 

11—13, D—3 

WIEF (VAX Vector Instruction Emulation 

Facility) . 

SHOW PROCESS/FULL command, 11-4 


11—4, D—3 


11-4,11-5,11-9, 


w___ 

/WAIT qualifier, CD—256 
Watchpoint 

aggregate, 3-17,11-3 
canceling, CD-34 
defined, 3-15 
displaying, CD—254 
effect on execution speed, 3-18 
global section, 10-15 10 OQ 

in tasking (multithread) program, 12-2d, 
12-24 

multiprocess program, 10-15 

nonstatic (stack or register) variable, 3-1 / 

register, 3-17 

setting, 3-15, CD-196 

shareable image, 3—20 

source display at, 6-7 

static variable, 3-17 

vector register, 11—3 

with DECwindows, 1-24 

WHEN clause 
example, 3-13 
format, CD-4 

WHILE command, 8-10, CD-268 

%WIDTH, C-6 

/WIDTH qualifier, 7-22, CD-181 

Window , 

See also Display, debugger, screen mode 
attribute, DECwindows, 1-10 
automatic (AUTO), DECwindows, 1-11 
default configuration, DECwindows, 1-4 
for debugger command interface 


7-14, 


7-14, 


Window 

for debugger command interface (cont cu 

DECwindows COMMAND box, 1-19,1-27 
DECwindows DECterm window, 1-33 
VWS window, 9-5, CD-150 
instruction (INST), DECwindows, 1-11, l" 21 
output (OUT), DECwindows, 1-10 
predefined, DECwindows, 1-9 
register (REG), DECwindows, 1-12 
screen-mode, creating definition for, 

CD-202 

screen-mode, defined, 7—2 
screen-mode, deleting definition of, 

CD " 35 

screen-mode, identifying, 7-14, CD 255 
screen-mode, predefined, CD-255, C-7 
screen-mode, specifying, 7-13 
selecting address expression from, 

DECwindows, 1—22 
source (SRC), DECwindows, 1-10,1-21 
/WORD qualifier, CD-60, CD-85 

Workstation . 

debugger commands for (when using VWb), 

CD-5 ^ , i i 

debugger DECwindows interface for, 1 l 
debugging DECwindows application, 1-32 
debugging screen-oriented program 

using separate DECterm window 1-33 
using separate VWS window, 9-5, CD-150 
popping debugger window (when using VWS), 

CD-162 , . , , 

separate, for debugger DECwindows interface, 

1 - 3 2 , • j 

separate debugger terminal-emulator window 

vi sing DECwindows (DECterm), 1-33 
using VWS, 9-5, CD-150 
terminal emulator screen size, 7-22, LD ioi 
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How to Order Additional Documentation 


Technical Support 

your electronic^ ^ n6eds ’ CaI1 80 °- 343 - 4 °40 before placing 

Electronic Orders 

"°*” e 

Telephone and Direct Mail Orders 


Your Location 

Continental USA, 
Alaska, or Hawaii 


Puerto Rico 
Canada 


International 

Internal 1 


Call 

800-DIGITAL 

809-754-7575 

800-267-6215 


Contact 

Digital Equipment Corporation 

P.O. Box CS2008 

Nashua, New Hampshire 03061 

Local Digital subsidiary 

Digital Equipment of Canada 
Attn: DECdirect Operations KA02/2 
PO. Box 13000 
100 Herzberg Road 
Kanata, Ontario, Canada K2K 2A6 

Local Digital subsidiary or 
approved distributor 

USASSB Order Processing - WMO/E15 
or 

U.S Area Software Supply Business 
JJigital Equipment Corporation 
Westminster, Massachusetts 01473 
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